Register a webhook endpoint

Outbound webhooks POST signed JSON to your URL when something happens. Open Settings → API & webhooks, then Manage endpoints and the delivery log. The page title is Webhooks.

Before you start

1. Sign in as an Admin. Standard members can view endpoints and the delivery log; they cannot register or change them.
2. Have a public HTTPS URL ready. The form help: “Must be https and reachable from the public internet. We do not follow redirects.”

Register an endpoint

1. Under Add an endpoint, enter the URL. It must start with https://, use a public DNS hostname (not an IP address typed into the field), and must not include a username or password in the address.
2. Optional: a description (up to 120 characters) so your team knows what owns the URL.
3. Tick at least one event:
   • Payment recorded
   • Invoice paid in full
   • Customer replied
   • Dispute raised
   • Promise to pay recorded
   • Promise broken
   • Chase completed
   • Accounting sync failed
4. Press Register endpoint.

Expected result

A flash reads “Endpoint registered. Copy the signing secret now — it cannot be shown again.” Copy it once. After that the row shows only a short hint. Until an endpoint exists, nothing is delivered. Delivery is queued so a slow receiver never blocks PayBlah.

How PayBlah calls you

• HTTPS only. PayBlah does not follow redirects. It POSTs to the public address it validated for that hostname.
• Send test event queues a test_event — not one of the eight live events — so you can prove reachability without your handler treating it as money.
• Pause stops new events being queued. Resume starts from then; it does not replay what was missed while paused.
• Rotate secret issues a new secret and the old one stops immediately.
• Remove archives the endpoint. Delivery history is kept.
• Edit then Save changes updates the URL, description, or events — not the secret.

Verify every request

Check the signature before you act. An unverified webhook is one anybody could have sent you. This is how you verify — not a recipe for forging a request.

1. Read the raw body bytes. Do not parse and re-encode JSON first — the signature is over the bytes.
2. Read the PayBlah-Signature header. It is t= a unix timestamp, a comma, then v1= a hex HMAC.
3. Build the signed string: the timestamp, a full stop, then the raw body.
4. HMAC-SHA256 that string with your endpoint signing secret, hex-encoded.
5. Compare with v1 in constant time.
6. Reject if t is more than 300 seconds from your clock.

Other headers: PayBlah-Event, PayBlah-Event-Id (the same on every retry and resend), PayBlah-Delivery, PayBlah-Attempt, and PayBlah-Version (currently 2026-07-26).

What is in a payload

Ids, amounts in minor units with currency, dates, and states. No customer name, email, phone, address, free-text reply, dispute reason, payment link, or portal token. Fetch more with your API key if you need it.

If something goes wrong

• Not HTTPS: “The URL must start with https:// — a signed payload sent over http can be read and rewritten in transit.”
• Local or private hostname: “That address is on the local network. Give a URL reachable from the public internet.”
• No events ticked: “Choose at least one event to send — an endpoint subscribed to nothing would never be called.”
• Lost signing secret: press Rotate secret, copy the new one, deploy it. The old secret stops at once.
• Standard user: “You can view webhook endpoints and the delivery log. Only an Admin can register or change them.”

PayBlah does not provide a native Zapier connection. Use a signed webhook from this page in your own workflow if you wish.