How do I test and secure an outbound webhook?

Each outbound webhook has a signing secret. Breakcold signs every message with it, so your endpoint can check that a message really comes from your workspace. Your outbound webhooks are in Settings → Webhooks.

Step by step

1. Open the webhook from Settings → Webhooks → Manage send webhooks.
2. Open the Security tab.
3. Reveal or copy the Signing Secret and store it in your endpoint's settings.
4. Open the Test tab.
5. Click Send Test Ping. Breakcold sends a signed webhook.test event and shows the result: Test successful — HTTP 200, or the error your endpoint returned.
6. Open the Delivery Logs tab to follow the real events: Event, Status, HTTP code, Attempt and Duration.
7. Each line is one attempt. A failed event is tried again after 5 seconds, then after 30 seconds.

Check the signature

Each message is a POST with these headers:

• X-Webhook-Signature: sha256= followed by the HMAC-SHA256, in hex, of the timestamp, a dot and the raw body, signed with the secret;
• X-Webhook-Timestamp: the time of sending, in Unix seconds;
• X-Webhook-Event: the event name, for example record.created;
• X-Webhook-Delivery-Id: the event ID, the same on every retry of one event. Use it to ignore duplicates.

In Node.js:

import crypto from "node:crypto";

function isFromBreakcold(rawBody, headers, secret) {
  const timestamp = headers["x-webhook-timestamp"];
  const expected =
    "sha256=" +
    crypto.createHmac("sha256", secret).update(`${timestamp}.${rawBody}`).digest("hex");
  const received = headers["x-webhook-signature"] ?? "";
  return (
    received.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected))
  );
}

Use the whole secret, whsec_ included, and the body exactly as received, before any JSON parsing.

Good to know

• Rotate Secret replaces the secret at once, with no confirmation. Messages signed with the old one stop matching, so update your endpoint right after.
• Any 2xx answer within 10 seconds counts as delivered. Otherwise Breakcold tries again, up to 3 attempts in all.
• After 50 failed attempts in a row, the webhook turns Disabled. Fix your endpoint, then click Activate at the top of the webhook's page.
• Pause stops sending. Events that happen while a webhook is paused or disabled are not sent later.
• The test ping isn't written to the Delivery Logs, and it is sent even when the webhook is paused.
• Delivery logs are kept for 30 days. Deleting a webhook deletes its logs.

Related

• How to send Breakcold events to another tool
• Webhook Sender events and payloads