payabli/integration-skills

payabli-webhooks

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 mul…

ソースを見る

使い方

  1. インストールコマンドをコピーし、自分の環境へ導入する前にソースを確認します。
  2. 必要なツール、認証情報、対応環境を原文で確認します。
  3. 入力と成果物を指定し、出力を資料と照合します。
npx skills add https://github.com/payabli/integration-skills --skill payabli-webhooks

開始前の確認

  • 導入にはモデル契約、API枠、ファイルへのアクセス許可は含まれません。
  • スター数や導入数は活動の指標であり、独立した品質・安全性試験ではありません。
リポジトリの原文

見出し、例、コード、表、リンク、参照画像を含む原文を表示しています。

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": "<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, 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

同じリポジトリから

関連する Skills

すべての Skills
payabli
コミュニティ

payabli-accept-payments

Use when writing code that accepts payments through Payabli: charging cards or ACH, integrating embedded payment components or a hosted payment page, handling Apple Pay or Google Pay, or processing voids and refunds. Boundaries — subscriptions: payabli-subscriptions; invoices and payment links: payabli-invoices; disputes and refund-failure recovery: payabli-disputes. Reads payabli-integration.md on load if present.

1時間の導入数
1
GitHub Stars
0
更新日
10月23日
payabli
コミュニティ

payabli-bills

Use when building accounts-payable automation on Payabli — capturing vendor bills (manual entry or OCR) and paying them through Pay Out. Distinct from raw payouts (payabli-send-payments): a bill is a captured vendor invoice that you then pay. Reads payabli-integration.md on load if present.

1時間の導入数
1
GitHub Stars
0
更新日
10月23日
payabli
コミュニティ

payabli-boarding

Use when onboarding merchants to Payabli through the API — creating the business, its people, paypoints, and bank accounts, opening a boarding application, validating and submitting it, answering underwriting requests, or tracking an application's status and enablement. Moving an existing integration off the legacy /Boarding/ endpoints lives in payabli-boarding-migration. Reads payabli-integration.md on load if present.

1時間の導入数
1
GitHub Stars
0
更新日
10月23日
payabli
コミュニティ

payabli-boarding-migration

Use when moving an existing integration off Payabli's legacy boarding endpoints (/Boarding/app, /Boarding/read, boarding links) to intelligent boarding — converting legacy application payloads to the new records, mapping fields, values, and statuses, or planning the cutover before the legacy sunset. Building boarding from scratch lives in payabli-boarding. Reads payabli-integration.md on load if present.

1時間の導入数
1
GitHub Stars
0
更新日
10月23日