Como usar
- Copie o comando e verifique o pacote antes de instalar no seu ambiente de agente.
- Consulte no original as ferramentas, credenciais e ambientes necessários.
- Descreva os dados de entrada e a entrega esperada; confira a saída com as fontes.
npx skills add https://github.com/payabli/integration-skills --skill payabli-webhooksAntes de começar
- A instalação não inclui assinatura de modelo, franquia API ou acesso aos seus arquivos.
- Estrelas e instalações indicam atividade, não um teste independente de qualidade ou segurança.
Renderizado do repositório de origem, preservando títulos, exemplos, código, tabelas, links e imagens.
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:
- Set a custom
Authorizationheader (viawebHeaderParameters) when you create the notification, and check it on receipt. - 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:
"content": {
"eventType": "approvedpayment",
"webHeaderParameters": [
{ "key": "Authorization", "value": "<your-shared-secret>" }
]
}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,targetto your endpoint URL, andcontent.eventTypeto the event to subscribe to. frequencyis required, and omitting it returns400. For an ongoing subscription, useuntilcancelled.ownerIdis the numeric ID of the owner thatownerTypenames: theorgIdfor an organization (ownerType: 0), or thepaypointIdfor a paypoint (ownerType: 2). Don't use the entrypoint name, the alias that appears in URL paths like/Customer/single/{entry}. A string value returns400.- The delivered payload's
Eventvalue can differ from theeventTypeyou subscribe with, by case or by name, so route on the delivered value. For example,payout_transaction_authorizedarrives asPayOutAuthorized. 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