Skip to main content

​
Webhooks

Webhooks push events to your server in real time as they happen.

​
1. Create an endpoint

Set up an HTTPS endpoint on your server that accepts POST requests. The SDK provides built-in signature verification: 
import { verifyWebhook } from "@messages-dev/sdk";

app.post("/webhooks", async (req, res) => {
  let event;
  try {
    event = await verifyWebhook(
      req.body,
      req.headers["x-webhook-signature"],
      "your_webhook_secret",
    );
  } catch (err) {
    console.error("Invalid signature");
    return res.sendStatus(400);
  }

  switch (event.event) {
    case "message.received":
      console.log(`${event.data.sender}: ${event.data.text}`);
      break;
    case "message.sent":
      console.log(`Delivered: ${event.data.id}`);
      break;
  }

  res.sendStatus(200);
});

​
2. Register the webhook

Go to Webhooks in your dashboard and click Add Webhook. Enter your endpoint URL, select message.received, and copy the signing secret.
The dashboard is the easiest way to create and manage webhooks. You can also use the API if you need to create them programmatically.

​
3. Verify signatures

Every delivery includes an X-Webhook-Signature header. The SDK handles this automatically via verifyWebhook(). If you’re not using the SDK: 
import { createHmac } from "crypto";

function verifyWebhook(body, signature, secret) {
  const expected = createHmac("sha256", secret)
    .update(body)
    .digest("hex");
  return expected === signature;
}
See Webhooks for the full list of events and more details.