# Webhooks

The Auvo API notifies task, ticket and service-order events via
**authenticated HTTP POST** to the client-registered URL.

## Subscribe to events

Use the **WebHooks** group in the API reference to create/list/remove
subscriptions. Each subscription holds:

- `url` — client endpoint (HTTPS required in production).
- `events` — event list (`task.created`, `task.updated`, `ticket.closed`...).
- `secret` — opaque string returned on creation; use it to sign payloads.


## Payload shape


```json
{
  "event": "task.created",
  "occurredAt": "2026-04-24T13:45:00Z",
  "deliveryId": "01J9F3T2...-",
  "data": { "taskId": 12345, "customerId": 98 }
}
```

## Origin validation

Every delivery includes `X-Auvo-Signature: t=<ts>,v1=<hexHmacSha256>` computed
as `HMAC_SHA256(secret, "${ts}.${body}")`. Reject when:

- The delta between `ts` and `Date.now()` exceeds **5 minutes**.
- `v1` does not match (use a time-safe comparison).


## Redelivery

- `2xx` responses within **10 s** mark the delivery as successful.
- Failures or timeouts trigger exponential-backoff retries for up to **24 h**.
- `X-Auvo-Delivery-Attempt` reports the current attempt (1..n).


## Idempotency

Use `deliveryId` to deduplicate deliveries on your side — retries reuse the
same ID.