Webhooks

​

Events

​

The request

POST /your/endpoint HTTP/1.1
Content-Type: application/json
User-Agent: Wiredesk-Webhooks/1.0
webhook-id: msg_2f8c0e4a9b7d4c1e8f3a6b5d0c9e7f12
webhook-timestamp: 1760000000
webhook-signature: v1,K5oZfzN95Z9UVu1EsfQmfVNQhnkZ2pj9o9NDN/H/pI4=

{
  "type": "message.created",
  "timestamp": "2026-10-08T14:03:12.000Z",
  "data": {
    "message": {
      "id": "982",
      "object": "message",
      "conversation_id": "2b0c…",
      "role": "agent",
      "text": "Saturdays we're open 10 to 4.",
      "created_at": "2026-10-08T14:03:12.000Z"
    },
    "conversation": { "id": "2b0c…", "object": "conversation", "channel": "chat", … }
  }
}

​

Check the signature

import { Webhook } from "standardwebhooks";

const wh = new Webhook(process.env.WIREDESK_WEBHOOK_SECRET); // "whsec_…"

app.post("/wiredesk", express.raw({ type: "application/json" }), (req, res) => {
  let event;
  try {
    event = wh.verify(req.body, req.headers); // throws if the signature or timestamp is wrong
  } catch {
    return res.status(401).end();
  }
  res.status(200).end();
  handle(event); // after answering
});

1. Base64-decode the secret after the whsec_ prefix. That is the HMAC key.
2. Compute base64(HMAC-SHA256(key, "<webhook-id>.<webhook-timestamp>.<raw body>")).
3. webhook-signature holds one or more v1,<signature> values separated by spaces. Accept the request if yours matches any of them, compared in constant time.
4. Reject a webhook-timestamp more than five minutes from your clock, so an old request cannot be replayed.

​

Retries

• webhook-id is the same on every attempt of one delivery. Use it to ignore one you already handled.
• Events can arrive out of order. Use timestamp, or the objects’ own timestamps, to order them.
• An endpoint whose deliveries have all failed for three days is switched off, and the page says why. Fix it, then switch it back on. Events from while it was off are not sent. Read them from the API.

​

Delivery log, test and rotate

• Send test event sends a signed webhook.test event straight away and tells you how it went. It is sent even when the endpoint is switched off, so you can check a fix first. It is never retried, and a failed test does not count toward the three days. Changing the endpoint’s address restarts that count.
• Rotate secret gives you a new signing secret. For the next 24 hours every delivery carries two signatures, one per secret, so you can deploy the new secret without failing any events. After that only the new one signs. Rotating again within those 24 hours replaces only the new secret: the one you started with keeps signing until its 24 hours are up.
• The signing secret is shown once, when you add the endpoint or rotate it. If you lose it, rotate.
• Switching an endpoint off stops its deliveries. Remove deletes it and its log.

​

Related

• REST API
• Notifications, for email and text alerts to your team
• Security model