Webhooks: events, verification, and retries

Events. zSign emits eight:

document.created, document.sent, document.viewed, document.signed, document.completed, document.declined, document.voided, document.expired

document.signed fires per signature; document.completed fires once, when the last one lands. If you are triggering downstream work off a finished agreement, use document.completed.

Verifying a delivery. Each request carries an HMAC-SHA256 signature header in the form t=<timestamp>,v1=<signature>. To verify: take the t value, build the string {timestamp}.{raw request body}, compute HMAC-SHA256 with your endpoint secret, and compare against v1 using a constant-time comparison. Verify against the raw body — re-serialized JSON will not match.

Signatures older than 5 minutes are rejected, so your server's clock needs to be roughly correct.

Retries. A failed delivery is retried up to 7 times (8 attempts total) at 1 min, 5 min, 15 min, 1 h, 3 h, 6 h, and 12 h — about 22 hours of coverage.

What counts as failure: 5xx and timeouts always retry. Most 4xx responses are treated as permanent, because a request your endpoint rejected as malformed will be rejected identically on the retry. 3xx is terminal — the delivery client does not follow redirects, so point the endpoint at its final URL.

Return a 2xx as soon as you have durably stored the event, then process it asynchronously. Slow handlers cause timeouts and retries, and retries mean you must handle the same event more than once.