Webhooks

Passage Connect sends ES256-signed webhooks when a link completes or fails.

Webhook delivery

When an automation finishes, the Connect Service sends a POST request to the webhookUrl specified when creating the link.

Payload format

The webhook body is a JSON object:


{
  "event": "link.complete",
  "linkId": "link_abc123",
  "status": "complete",
  "result": { ... },
  "error": null,
  "timestamp": 1704067200000
}

The event field is either link.complete or link.failed.

Signature

Webhooks include two headers for verification:

Header	Description
`X-Passage-Signature`	ES256-signed JWT containing a SHA-256 hash of the request body
`X-Passage-Timestamp`	Unix timestamp (seconds) when the webhook was signed

The JWT header contains the kid (key ID) used to look up the public verification key.

Retry policy

Webhooks are retried up to 3 times with exponential backoff:

Immediate first attempt
Retry after 1 second
Retry after 5 seconds

If all attempts fail, the webhook is dropped. The link status is still updated in the database regardless of webhook delivery.

Next steps

Webhook Verification Guide — Step-by-step verification
Webhook Key API — Fetch the verification key