> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kuahr.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks overview

> Receive Kua events at your own endpoint in real time.

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

<CodeGroup>
  ```bash cURL theme={null}
  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"
    }'
  ```

  ```ts Node theme={null}
  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
  ```

  ```python Python theme={null}
  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
  ```
</CodeGroup>

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

## Delivery, retries, and ordering

* Kua `POST`s a JSON [event envelope](/webhooks/events) 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.

<CodeGroup>
  ```bash cURL theme={null}
  # 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"
  ```

  ```ts Node theme={null}
  await kua.webhooks.ping(endpoint.id);
  const deliveries = await kua.webhooks.deliveries(endpoint.id);
  ```

  ```python Python theme={null}
  kua.webhooks.ping(endpoint.id)
  deliveries = kua.webhooks.deliveries(endpoint.id)
  ```
</CodeGroup>