Receive your first webhook

Before you start

You need an authorised Live key for the endpoint’s company with webhooks:write, a reachable HTTPS receiver, a secret manager and durable event-ID deduplication. Test keys cannot register, read, ping, delete or replay webhooks (400 TEST_MODE_UNSUPPORTED). A signed ping lets you verify the receiver without creating a payroll payment.

Configure your receiver to verify the raw body using the signature guide, durably accept the event and return 2xx only after acceptance. All requests use https://api.kuahr.com. Set KUA_API_KEY to the company’s authorised Live credential.

Register the receiver

Replace https://your-app.example/kua/webhooks with your real HTTPS receiver. Choose only the event types you need; the API accepts a comma-separated string or *.

curl --fail-with-body "https://api.kuahr.com/v1/webhooks" \
  -X POST -H "X-Api-Key: $KUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://your-app.example/kua/webhooks","description":"Company integration receiver","eventTypes":"payroll.run.disbursed,employee.created"}'

Save the returned endpoint id as ENDPOINT_ID. Store the one-time secret securely as the receiver’s KUA_WEBHOOK_SECRET; do not copy it into logs or support messages. Configure the verifier before sending a ping. In an SDK, registration is kua.webhooks.create(...) with Node eventTypes or Python event_types.

If registration’s response is lost, list endpoints and reconcile the intended URL before creating another. The signing secret cannot be assumed recoverable from the list; use the authorised rotation journey if the one-time secret was lost.

Test and verify

# Queue a sample event. This does not prove receipt.
curl --fail-with-body -X POST "https://api.kuahr.com/v1/webhooks/$ENDPOINT_ID/ping" \
  -H "X-Api-Key: $KUA_API_KEY"

# Inspect the receiver's delivery records.
curl --fail-with-body "https://api.kuahr.com/v1/webhooks/$ENDPOINT_ID/deliveries" \
  -H "X-Api-Key: $KUA_API_KEY"

SDK equivalents are kua.webhooks.ping(endpointId) and kua.webhooks.deliveries(endpointId) in Node, or the same methods with endpoint_id in Python.

Find the ping delivery by its ID and inspect its status, attempt count, response code and error. Match the verified body ID in your durable receiver records. Done when: the delivery is Succeeded, the receiver retained it, and a duplicate verified event would not repeat the business effect. Sending a ping or receiving an accepted/queued response is not this completion state.

Handle retries and ordering

Kua delivers event envelopes at least once and does not promise strict ordering. Respond with any 2xx within 10 seconds. Failures and timeouts retry with exponential delays of approximately 1 minute, 5 minutes, 30 minutes, 2 hours and 6 hours, up to six total attempts, then become Exhausted.

A crash after your side effect but before acknowledgement can produce another attempt. Deduplicate the verified body’s event ID, not the attempt signature. For changing entity state, reconcile with authoritative records instead of assuming arrival order. Unknown event types must not cause endless retries.

Recover an exhausted delivery

Repair the receiver, inspect retained attempts and follow manual recovery. History and replay are available at api.kuahr.com. It requires a specific recovery grant, persisted request key and audit reason. A replay accepted as Pending is queued, not delivered; the original event ID stays the same.

Rotate a signing secret

Use dashboard-only signing-secret rotation. New attempts change immediately; there is no promised grace period for the old secret. An SDK key cannot rotate it.

Stop receiving events

After the company authorises removal, use DELETE /v1/webhooks/{id} or kua.webhooks.delete(id) in Node / kua.webhooks.delete(id) in Python with webhooks:write. This affects the endpoint’s future deliveries; do not expect a deleted endpoint to remain replayable. Retain your required audit records before removal, then list endpoints to verify it is absent. If a delete response is lost, reconcile the list before retrying or registering a replacement.

Continue with the event catalog, event reconciliation and go-live checklist.