Skip to main content

Webhooks

Webhooks push events to your server the moment they happen: charges created and paid, approvals requested, budgets exhausted. Every delivery is signed with HMAC-SHA256 so you can prove it came from Payzor.

1. Register an endpoint

From a console session:
Response: the signing secret is shown once:
An empty events array means all events. Pass a subset to filter, e.g. "events": ["payment.succeeded", "budget.exhausted"].

2. Receive deliveries

Each POST to your endpoint includes: The body is a JSON envelope; data holds the event payload:

3. Verify the signature

The signature is computed over the raw body bytes (not re-serialized JSON) as:
where <t> is the timestamp from the signature header. Compare with a timing-safe equality.
Verifying against the raw body matters: if you parse and re-stringify JSON first, key order or float formatting can change and verification will fail even for legitimate calls.
Optionally also check that t is within ~5 minutes of now (replay protection).

4. Respond fast, process async

Return any 2xx quickly. If your handler throws, Payzor retries with exponential backoff. Deliveries are kept in memory per endpoint; inspect recent ones at:

Event catalog

Full payloads: Webhook Events Reference.
Treat webhook handlers as idempotent. Retries mean you may receive the same event more than once, dedupe on event.id.