Skip to main content
Webhooks are optional. They tell you promptly that something changed; the change feed remains the source of truth for recovery. Every notification is a hint to go and read, never a copy of the data.

​
What a notification contains

A notification names the Client, the resource, the kind of change and the accepted revision. It carries no Customer, contact or financial detail.
eventId is the same identity the change feed reports for the change. To see the detail, read the resource with its own GET and your API key. That read is authorized when you make it, so a revoked grant or missing scope cannot recover data through a notification.

​
Configure the endpoint

All four operations need the webhooks:manage scope. Each Integration has at most one endpoint per Client.
  • PUT /v1/clients/{clientCode}/webhook-endpoint with { "url": "https://hooks.example.com/paypathiq" } creates or replaces the endpoint and re-enables a disabled one. The first call returns 201 with signingSecret, shown once. Later calls return 200 without it.
  • GET /v1/clients/{clientCode}/webhook-endpoint returns url, status, disabledReason and secretVersion.
  • POST /v1/clients/{clientCode}/webhook-endpoint/rotate-secret issues a new signing secret, shown once.
  • POST /v1/clients/{clientCode}/webhook-endpoint/disable stops delivery.
The URL must be https on port 443 with a public DNS name, no credentials and no fragment. Other URLs return 422 webhook_destination_unsafe. Notifications cover changes that commit after you configure the endpoint. Use the change feed for anything earlier.

​
Verify the signature

Each request carries two headers: PayPathIQ-Event-Id and PayPathIQ-Signature.
  1. Read the raw request body before parsing it.
  2. Compute the hex HMAC-SHA256 of <t>.<raw body>, keyed with your signing secret (the whole whsec_... string).
  3. Compare it with every v1 value using a constant-time comparison. Accept if any matches.
  4. Reject the request when t is more than five minutes from your clock.

​
Rotate the secret

Rotation returns a new secret. For 24 hours afterwards every notification is signed with both the new and the previous secret, so you can deploy the new one before the old one stops being accepted. Because a v1 value is present for each, verification by “any match” works throughout. PayPathIQ never writes signing secrets, signatures or destination URLs to logs or audit events. Audit events record a digest of the change only.

​
Delivery, retries and recovery

Respond with any 2xx status within 5 seconds. Redirects are not followed. Any other outcome is retried after 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours, 12 hours and 24 hours, for 8 attempts in all over about two days. After that the delivery is abandoned. Delivery is at least once and unordered. Retries mean a later change can arrive before an earlier one, and a retry can repeat a notification you already handled.
  • Discard an eventId you have already handled.
  • Compare revision with the revision you hold and ignore anything not newer.
  • When you suspect a gap, for example after an outage or an abandoned delivery, resume the change feed from your stored cursor. Missed, duplicate and out-of-order notifications all converge on the same state.
Delivery records, like change-feed events, are kept for 30 days.

​
Revocation and unsafe destinations

PayPathIQ re-checks the destination and your current grant before every attempt, including retries:
  • The grant must still be active and approved for the Client, and must still hold the read scope for the resource type. Without that scope the notification is not sent.
  • The destination must still pass the checks above, including DNS resolution to public addresses, and the connection itself refuses non-public addresses.
If the grant is revoked the endpoint is disabled with disabledReason grant_revoked. If the destination stops being safe it is disabled with destination_unsafe. Configure the endpoint again once the cause is fixed.

​
Where the limits come from

The limits follow from how the worker runs, not from production traffic measurements. The delivery worker runs every minute. It sends at most 10 notifications per endpoint per run, each with a 5 second timeout, so one slow endpoint cannot use more than about 50 seconds of a run or delay another endpoint. The retry schedule spans about 44 hours, so the 30 day retention comfortably covers the whole life of a delivery and matches the change feed. PayPathIQ will revisit these numbers when sandbox and production volumes are measured.