Webhooks overview

Instead of polling /v1/events, register a webhook and Kua will POST each matching event to your URL as it happens — signed, retried, and logged.

Register an endpoint

curl https://api.kuahr.com/v1/webhooks \
  -X POST \
  -H "X-Api-Key: kua_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/kua/webhooks",
    "description": "Production receiver",
    "eventTypes": "payroll.run.disbursed,employee.created"
  }'

const endpoint = await kua.webhooks.create({
  url: "https://your-app.com/kua/webhooks",
  description: "Production receiver",
  eventTypes: "payroll.run.disbursed,employee.created",
});
console.log(endpoint.secret); // whsec_… — store it

endpoint = kua.webhooks.create(
    url="https://your-app.com/kua/webhooks",
    description="Production receiver",
    event_types="payroll.run.disbursed,employee.created",
)
print(endpoint.secret)  # whsec_… — store it

The response includes a signing secret (whsec_…) shown once — store it; you’ll use it to verify signatures. Set eventTypes to a comma-separated list, or * for all events.

Delivery, retries, and ordering

Kua POSTs a JSON event envelope to your URL.
Respond with any 2xx status within 10 seconds to acknowledge receipt.
On a non-2xx or timeout, Kua retries with exponential backoff (~1m, 5m, 30m, 2h, 6h) up to 6 attempts, then marks the delivery exhausted.
Delivery is at-least-once and not strictly ordered — dedupe on the event id and treat handlers as idempotent.

Test it

Send yourself a sample event, then inspect recent attempts — each delivery row shows the status, attempt count, response code, and last error.

# Send a test event
curl https://api.kuahr.com/v1/webhooks/{id}/ping \
  -X POST -H "X-Api-Key: kua_live_your_key_here"

# Inspect recent attempts
curl https://api.kuahr.com/v1/webhooks/{id}/deliveries \
  -H "X-Api-Key: kua_live_your_key_here"

await kua.webhooks.ping(endpoint.id);
const deliveries = await kua.webhooks.deliveries(endpoint.id);

kua.webhooks.ping(endpoint.id)
deliveries = kua.webhooks.deliveries(endpoint.id)

​Register an endpoint

​Delivery, retries, and ordering

​Test it

Register an endpoint

Delivery, retries, and ordering

Test it