Webhooks

In the dashboard under Settings → Webhooks, or over the API:

curl -X POST https://api.integrable.cloud/api/webhooks \
  -H "Authorization: Bearer $INTEGRABLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/hooks/integrable",
    "events": ["lead.captured", "handoff.requested"],
    "description": "CRM sync"
  }'

The URL must be public HTTPS. Private, loopback and link-local addresses are refused when you save the endpoint and again on every delivery, because a name that resolved publicly at registration can be re-pointed at an internal address afterwards.

GET /api/webhooks/events returns this catalogue with a sample payload for each, so you can build against a real shape before any traffic exists.

The signature is an HMAC-SHA256 over <timestamp>.<raw body>, keyed with your endpoint's secret, in the form t=<timestamp>,v1=<hex>.

Sign the raw bytes you received. Parsing the JSON and re-serialising it changes whitespace and key order, and the signature will never match.

import crypto from "node:crypto";

function verify(rawBody, header, secret, toleranceSeconds = 300) {
  const parts = Object.fromEntries(
    header.split(",").map((p) => p.split("=").map((s) => s.trim())),
  );
  const timestamp = Number(parts.t);
  if (!timestamp || Math.abs(Date.now() / 1000 - timestamp) > toleranceSeconds) {
    return false; // too old, or re-dated by an attacker
  }

  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${timestamp}.`)
    .update(rawBody)
    .digest("hex");

  const a = Buffer.from(expected, "utf8");
  const b = Buffer.from(parts.v1 ?? "", "utf8");
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

import hashlib, hmac, time

def verify(raw_body: bytes, header: str, secret: str, tolerance: int = 300) -> bool:
    parts = dict(p.strip().split("=", 1) for p in header.split(","))
    timestamp = int(parts.get("t", 0))
    if not timestamp or abs(time.time() - timestamp) > tolerance:
        return False

    expected = hmac.new(
        secret.encode(), f"{timestamp}.".encode() + raw_body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, parts.get("v1", ""))

The timestamp is inside the signed material specifically so replay detection works: an attacker who captured a valid delivery cannot re-date it without invalidating the signature. Reject anything outside a few minutes.

Delivery is at least once. A network failure after your server committed but before it answered produces a retry of work you already did — so key on x-webhook-delivery, which is unique per attempt-group, and ignore one you have seen.

Answer 2xx quickly and do the work afterwards. A receiver that takes ten seconds to reply gets retried while it is still working.

Failures are classified rather than blindly retried. A connection reset or a 503 is transient and comes back with backoff; a 404 or a TLS failure is not going to fix itself and is recorded rather than hammered.

The delivery log is at GET /api/webhooks/deliveries, with per-endpoint health, the response you returned, and the reason a delivery is being retried.

curl -X POST \
  https://api.integrable.cloud/api/webhooks/deliveries/$DELIVERY_ID/replay \
  -H "Authorization: Bearer $INTEGRABLE_API_KEY"

A replay writes a new delivery record rather than overwriting the failure it is replaying — so the history of what went wrong survives the fix.

POST /api/webhooks/{id}/test fires a sample payload down the real delivery path — the same signing, the same URL guard, the same retry classification. If a test fire arrives and verifies, so will a real one.

Rotating a secret is POST /api/webhooks/{id}/rotate-secret. Deploy the new secret to your receiver first if you can accept both during the changeover — see versioning for how we signal changes generally.