Outgoing webhooks

Setting one up

1. 1

   Settings → Webhooks → add endpoint

   It must be a public HTTPS URL that answers quickly.

2. 2

   Choose the events

   Subscribe only to what you consume. Every event you ignore is latency you pay for.

3. 3

   Store the signing secret

   Shown once, used to verify that a delivery really came from PipSync.

4. 4

   Send a test delivery

   It shows the exact payload and your endpoint's response, which is usually enough to finish the integration.

Verifying the signature

Each delivery carries an HMAC signature over the raw request body. Verify it against the raw bytes before parsing — re-serialised JSON will not match.

import crypto from "node:crypto";

function verify(rawBody, signature, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signature),
  );
}

Retries and idempotency

• Answer 2xx as fast as you can and do the work asynchronously. Slow endpoints get treated as failures.
• Non-2xx responses are retried with backoff; repeated failures disable the endpoint and notify you.
• Deliveries can arrive more than once. Deduplicate on the event id — assume at-least-once, never exactly-once.
• Order is not guaranteed. Use the event timestamp, not arrival order, to reconstruct a sequence.