# Webhooks

> Let another system know automatically when an invoice is reported, paid or received. Setup is in the app; the technical details are on docs.alyabooks.ai.

Source: /help/en/account-and-setup/webhooks-overview

A webhook is a web address of your ERP, accounting tool or automation platform that Alya Books calls whenever something happens. Your developer gives you the address; you register it here.

## Steps

1. Open **API access** in the sidebar (System group) and choose the **Webhooks** tab. You need the owner or admin role, or the "Manage webhooks" permission.
2. Click **New webhook** and fill in:
- **Target URL**: must be a public `https://` address. Private or plain `http://` addresses are refused.
- **Name** and an optional **Description**.
- **Events**: tick the ones you need, or **All events**.
- **Custom headers** if your developer asks for them, and the **Active** switch.
3. Click **Create webhook**. A signing secret is shown once; copy it and pass it to your developer, who uses it to verify each call.
4. From the row menu, use **Send test** to check the endpoint, **Deliveries** to see every attempt with status and response, **Pause** or **Resume**, **Rotate secret**, **Edit** or **Delete**.

## Common events

| Event | Sent when |
|---|---|
| `invoice.created`, `invoice.submitted`, `invoice.reported`, `invoice.rejected` | An invoice moves through the FTA lifecycle |
| `invoice.paid`, `invoice.overdue` | Payment recorded or due date passed |
| `incoming.created`, `incoming.validated`, `incoming.accepted` | A supplier invoice arrives and is reviewed |
| `quote.sent`, `reminder.sent`, `document.sent` | A document leaves by email |
| `customer.created`, `product.created` | Master data added |

## Good to know

- Failed calls are retried after at least 1 minute, 5 minutes, 30 minutes, 2 hours and 12 hours (retries are sent by a job that runs every 5 minutes); after six attempts the delivery is marked failed and can be retried by hand.
- A webhook pauses itself after 25 consecutive exhausted deliveries; fix the endpoint and click **Resume**.
- Webhooks work for every mode, including Test (simulated), so you can integrate before going live.
- Each call carries the headers `X-Webhook-Event`, `X-Webhook-Event-Id`, `X-Webhook-Delivery` and `X-Webhook-Attempt`, the signature in `X-Webhook-Signature`, and the user agent `Webhook-Delivery/1.0`; custom header names cannot start with `X-Webhook-`. Your developer verifies the signature with the signing secret.
- Payload formats, headers and signature verification: see the developer documentation at docs.alyabooks.ai.

## Related

- [Extra permissions for team members](/help/en/account-and-setup/member-permissions)
- [Check whether an invoice was delivered](/help/en/settings/check-invoice-delivery)