Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.periskope.app/llms.txt

Use this file to discover all available pages before exploring further.

While building your own WhatsApp integrations with Periskope, you might want to listen to events in real time. You can do this with Periskope’s Webhooks. Simply register a Webhook endpoint with Periskope and start receiving different events occuring inside the Periskope platform. You can also receive events with our Typescript SDK

​
Prerequisites

  1. A Periskope account: To use the Periskope API, you need to have a Periskope account. If you don’t have one, you can sign up for a free trial here.
  2. An HTTP POST / Endpoint: Prepare your server to start receiving POST requests. Your server should have an endpoint ready to catch data sent by Periskope when events are sent.
In order to start receiving webhooks, you need to have a server that can handle incoming HTTP POST requests. The POST request endpoint needs to be open and publicly accessible without any authentication.

​
Setting up webhooks on Periskope 🔧

You can access the webhook configuration through your Periskope settings or click here to visit. Here, you can manage and set up new webhooks.
1

Add webhook 🔌

Click on the Add Webhook button. This opens a modal where you can enter the URL that will receive the webhook POST requests.
Step 1
2

Choose events 🏁

Choose the events you want to subscribe to from the list below. Each event corresponds to different actions or changes in Periskope and whatsapp that you can receive notifications for.
3

Create a Signing Key 🔑

Step 3
Signing Keys are used to verify that the webhook events that you receive on your destination come from a trusted source. You can generate a Signing Key on the Webhook Screen by clicking on the Generate button. After copying your Signing Key, do not share it to keep it protected. Learn more about how to verify your Signing Key on your server here.
4

Done ✅

After configuring the URL and selecting the desired events, save your settings to activate the webhook.

​
Result 🚀

Webhooks are now setted up on your Periskope account. Your endpoint will now receive HTTP POST requests whenever the subscribed events occur on the Periskope platform.
You can test your webhook by triggering any selected event from the Periskope platform.

​
Event structure 📦

You’ll be receiving the data in the following format: 
{
  "event": "<event-type>",
  "data": "<event-data>", // complete data object as mentioned in Objects section
  "org_id": "<your-organisation-id>",
  "timestamp": "<timestamp>" // timestamp of the event creation
}

​
Verifying your Signing Key

A signing key is used to verify that the events received in your webhook endpoints are from a trusted source. Periskope generates an encrypted HMAC key for every request and sends the key in the x-periskope-signature header. On your webhook endpoint, you can check this signature by decrypting the secret key and verifying the legitimacy of a request. You can generate your Singing Key from Settings > Webhooks screen.
Step 3
Follow the code snippet below to verify your signing key on your server: 
import * as express from "express";
import { createHmac } from "crypto";

// Replace this with your actual signing key obtained from the Periskope dashboard (to be stored in .env)
const SHARED_SECRET = "YOUR_SIGNING_SECRET"; 

const app = express();

app.use(express.json());

// Verification function to check the signature of the request
function verifySignature(rawBody: Record<string, any>, signature: string) {
  // Create an HMAC SHA256 hash using the shared secret key
  const hmac = createHmac("sha256", SHARED_SECRET);


  // Update the HMAC hash with the stringified payload
  hmac.update(JSON.stringify(rawBody));
  
  // Calculate the HMAC digest in hexadecimal format
  const digest = hmac.digest("hex");
  
  // Compare the calculated digest with the signature provided in the header
  return digest === signature;
}

// Webhook endpoint handler for POST requests to /webhook
app.post("/webhook", (req: express.Request, res: express.Response) => {
  // Extract the signature from the 'x-periskope-signature' header
  const signature = req.headers["x-periskope-signature"] as string;

  // Verify the signature of the incoming request.
  // It's important to use the raw request body before any parsing/modification
  // if your framework modifies the body.
  // Here, we assume `req.body` contains the parsed JSON object.
  const isValid = verifySignature(req.body, signature);

  // If the signature is invalid, respond with an Unauthorized status
  if (!isValid) {
    return res.status(401).send("Invalid signature");
  }

  // If the signature is valid, process the webhook event
  console.log("Received valid webhook event:", req.body);
  // Add your custom logic here to handle the event (e.g., update database, send notifications)

  res.status(200).send("ok");
});

const PORT = 3000;
app.listen(PORT, () => {
  console.log(`Webhook server listening on port ${PORT}`);
});