Webhooks allow your application to receive real-time notifications when events occur in Signstack. Configure webhook endpoints to be notified about workflow lifecycle events (started, completed, failed), step events (started, completed), participant events (task assigned, signing completed, declined), and envelope events (sent, completed, voided).

Each webhook endpoint specifies a URL endpoint and the event types to subscribe to. When an event occurs, Signstack POSTs a signed JSON payload to your endpoint.

Payload shape

Every delivery body is a JSON envelope:

{
  "apiVersion": "1",
  "eventType": "workflow.completed",
  "eventId": "wf_01jv8m7qfj6xj9gkz7a4s2h8e",
  "timestamp": "2026-04-25T14:30:00.000Z",
  "orgId": "org_01jv8m7qfj6xj9gkz7a4s2h8e",
  "namespaceKey": "production",
  "mode": "live",
  "data": { /* event-specific payload */ }
}

Routing fields:

• apiVersion identifies the payload schema. Branch on this in your handler — when we ship a backwards-incompatible change, the new shape will go out under a new version ("2", etc.) and your existing code will keep receiving the version it was built against.
• namespaceKey + orgId identify which webhook endpoint fired. Useful when a single handler URL receives events from multiple namespaces.
• mode is "test" or "live", mirroring the namespace's mode. Critical safety signal — branch on this to make sure test workflows never write to your production systems.

Verification

We sign every delivery with HMAC-SHA256(secret, '<t>.<raw-body>') and ship the signature in the X-Webhook-Signature header:

X-Webhook-Signature: t=1714058200000,v1=<sig>[,v1=<sig>...]

• t= — unix-millisecond timestamp the signature was computed against
• v1= — scheme version + signature; multiple v1= entries appear during a rotation grace window — your verification passes if any of your stored secrets produce a match
• Reject events whose t= is more than 5 minutes from your server's clock to prevent replay attacks

Use the webhook secret returned at create / rotate time to verify; if you lose it, rotate (with a grace period) — never expose the secret to client-side code.

Delivery semantics

Signstack automatically retries failed deliveries with exponential backoff for up to 3 days, then gives up. Events are delivered at least once — implement idempotency in your handler by deduping on eventId.

Monitor delivery status and review past attempts via the deliveries endpoints below.