> For the complete documentation index, see [llms.txt](https://docs.limephone.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.limephone.io/workspace/webhooks.md).

# Webhooks

Send real-time call, message, and lead events from LimePhone to your own systems.

Webhooks let LimePhone notify your CRM, helpdesk, or custom application the moment something happens on your numbers. **Settings → Webhooks** configures one outbound endpoint for your workspace: an enable toggle, the destination URL, an optional signing secret, and toggles for each event.

Developers who need multiple subscriptions can manage them via the API — see [docs.limephone.io/api-reference/webhooks](https://docs.limephone.io/api-reference/webhooks).

## Supported events

| Toggle           | Event              | Fires when                          |
| ---------------- | ------------------ | ----------------------------------- |
| Message received | `message.received` | A message arrives on your number.   |
| Message sent     | `message.sent`     | A message is sent from your number. |
| Call received    | `call.created`     | A call comes in.                    |
| Call ended       | `call.completed`   | A call finishes.                    |
| Lead created     | `contact.created`  | A new lead is created.              |
| Lead updated     | `contact.updated`  | A lead is updated.                  |

## Set up your webhook

1. Open **Settings → Webhooks**.
2. Enter the HTTPS URL of your endpoint and, optionally, a signing secret.
3. Toggle on the events you want, and enable the webhook.

## How deliveries work

Each event is sent as a JSON `POST` to your URL, with these headers:

* `X-Webhook-Event` — the event name (for example `call.completed`).
* `X-Webhook-Delivery-Id` — a unique ID for this delivery.
* `X-Webhook-Signature` — present when you've set a signing secret (see below).

Your endpoint has **10 seconds** to respond with a success status. Failed deliveries are retried with backoff, so make your handler idempotent — you can receive the same event more than once.

## Verifying signatures

If you set a signing secret, each delivery includes an `X-Webhook-Signature` header: an HMAC-SHA256 of the string `{timestamp}.{deliveryId}.{rawBody}`, computed with your secret. Recompute it on your side and compare before trusting the payload. Also:

* Serve your endpoint over **HTTPS** only.
* Validate and sanitize incoming data before processing it.

## Common uses

* Log calls, messages, and leads in your CRM automatically.
* Alert your team about call activity.
* Trigger automated follow-ups when a message arrives.
* Feed activity into your own analytics or AI workflows.