--- name: payabli-webhooks description: >- Use when writing or modifying a webhook handler for Payabli events — receiving and processing event payloads, acknowledging delivery, authenticating incoming webhooks, handling retries idempotently, configuring event subscriptions, routing events across multiple paypoints, or weighing the webhooks-vs-polling tradeoff. Reads payabli-integration.md on load if present. metadata: author: payabli version: "0.1" --- # Payabli webhooks Receive Payabli events, acknowledge them, and process them safely. ## Load fundamentals first If `payabli-fundamentals` is not already loaded, load it now, then continue. ## On load If `payabli-integration.md` exists at the repo root, read it; honor its `## Webhooks` scope and `## Paypoint model`. ## How delivery works An event is queued and POSTed to your endpoint; **return HTTP 200 to acknowledge**. If you don't return success, Payabli retries (a small number of times, minutes apart), then marks the delivery failed and exposes it for manual retry. Treat retries as expected, not exceptional. https://docs.payabli.com/guides/pay-ops-notifications-webhooks-overview.md ## Authenticate the webhook — there is no signature **Payabli does not sign webhook payloads.** There is no HMAC or signature to verify — do not implement signature verification. Authenticate incoming webhooks two ways instead: 1. Set a custom `Authorization` header (via `webHeaderParameters`) when you create the notification, and check it on receipt. 2. Allowlist Payabli's documented sending IP addresses (listed under "IP addresses for webhook requests" in the notifications & webhooks overview: https://docs.payabli.com/guides/pay-ops-notifications-webhooks-overview.md; they differ by environment). `webHeaderParameters` lives inside `content` and is an array of `{key, value}` pairs. Payabli sends whatever you configure **verbatim** — there is no signing or token scheme, so the value is just your shared secret as-is (no `Bearer`/`Basic` prefix is required or interpreted). Check for the exact same string on receipt: ```json "content": { "eventType": "approvedpayment", "webHeaderParameters": [ { "key": "Authorization", "value": "" } ] } ``` Because Payabli echoes this header verbatim, the value on the subscription and the value your receiver checks must match exactly — use one secret for both. If they drift, deliveries still **reach** your endpoint but your receiver rejects them: a 403 that looks like a delivery failure even though the tunnel is fine. **Always return 200 — even on a bad or missing header.** The header check decides whether to *process* the event, not what HTTP status to return. A non-2xx makes Payabli retry and then mark the delivery failed, so you lose the event to your own auth. On a mismatch, log it and skip processing, but still return 200. Payabli doesn't require receiver auth, so treat the header as an advisory filter, not a gate on the response. (Accepting deliveries with no secret configured — for local development — is fine for the same reason.) For money-critical events, do not trust the payload alone: confirm by re-querying the transaction via the API (correlate on `transId`). This is the same discipline as idempotency in `payabli-fundamentals`. ## Process idempotently Retries and at-least-once delivery mean you will see duplicates. Dedupe on event identity (for example `transId`) and make handling idempotent so a repeat delivery is a no-op. ## Configure a subscription Create a notification with `POST /Notification`. For the full request body, see https://docs.payabli.com/developers/api-reference/notification/add-notification.md. Watch for these: - For a webhook, set `method: web`, `target` to your endpoint URL, and `content.eventType` to the event to subscribe to. - `frequency` is required, and omitting it returns `400`. For an ongoing subscription, use `untilcancelled`. - `ownerId` is the numeric ID of the owner that `ownerType` names: the `orgId` for an organization (`ownerType: 0`), or the `paypointId` for a paypoint (`ownerType: 2`). Don't use the entrypoint name, the alias that appears in URL paths like `/Customer/single/{entry}`. A string value returns `400`. - The delivered payload's `Event` value can differ from the `eventType` you subscribe with, by case or by name, so route on the delivered value. For example, `payout_transaction_authorized` arrives as `PayOutAuthorized`. To find both names for any event, look it up in the event tables at https://docs.payabli.com/guides/pay-ops-notifications-webhooks-overview.md and open its payload page. https://docs.payabli.com/guides/pay-ops-developer-notifications-manage.md ## Local development Payabli must POST to a publicly reachable URL, so `localhost` won't receive deliveries. Expose your handler with a tunnel and set the notification `target` to the tunnel's public HTTPS URL plus your handler path. **localhost.run** is one option — no account or install, just SSH: `ssh -R 80:localhost:3000 nokey@localhost.run` prints a public HTTPS URL (use your handler's port). ngrok and cloudflared also work. The auth header travels in the subscription's `webHeaderParameters`, not in the request you make from your app. Redo two things when they change: if the tunnel URL rotates (it does each restart on the free tiers), update `target`; if you rotate the shared secret, update `webHeaderParameters` too — the secret is baked into the subscription, not read live. Not every event can be triggered on demand in sandbox: payment-event webhooks fire when you run the transaction, but chargebacks, ACH returns, and similar require Payabli to trigger them (see `payabli-testing`). ## Route across multiple paypoints Subscribe at the **organization** level (`ownerType: 0`, `ownerId` = the `orgId`) to cover all paypoints, or per **paypoint** (`ownerType: 2`, `ownerId` = the `paypointId`). Configuring the same event at both levels delivers duplicates. Use `internalData` to tag events with a routing key when one endpoint serves many paypoints. ## Webhooks vs. polling Use webhooks for real-time reactions (payment approved, payout paid, invoice paid). Use polling for reconciliation, backfill, and audits. https://docs.payabli.com/guides/pay-ops-notifications-webhooks-vs-polling.md Building it end to end: https://docs.payabli.com/guides/pay-ops-developer-webhooks-quickstart.md