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

# Webhooks API

Manage webhook subscriptions programmatically.

| Method   | Path             | Scope            |
| -------- | ---------------- | ---------------- |
| `GET`    | `/webhooks`      | `webhooks:read`  |
| `GET`    | `/webhooks/{id}` | `webhooks:read`  |
| `POST`   | `/webhooks`      | `webhooks:write` |
| `PATCH`  | `/webhooks/{id}` | `webhooks:write` |
| `DELETE` | `/webhooks/{id}` | `webhooks:write` |

This manages *subscriptions*. For what the deliveries contain and how to handle them, see [Webhook events](/developers/webhook-events.md).

## Create a subscription

```bash
curl -X POST https://app.limecall.com/api/v1/webhooks \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/hooks/limecall",
    "events": ["call.completed", "message.received"],
    "description": "Production CRM sync",
    "maxRetries": 5
  }'
```

| Field         | Rules                               |
| ------------- | ----------------------------------- |
| `url`         | Must be a valid URL.                |
| `events`      | Array, **at least one** entry.      |
| `description` | Optional, for your own bookkeeping. |
| `maxRetries`  | Integer `0`–`10`. Defaults to `3`.  |

Returns `201` with the created subscription.

{% hint style="warning" %}
The response includes a generated **`secret`**. This is how you verify that a delivery genuinely came from LimeCall. Store it when you create the subscription — treat it like a password, and never skip the verification step, because your endpoint URL is reachable by anyone who learns it.
{% endhint %}

## Update

```bash
curl -X PATCH https://app.limecall.com/api/v1/webhooks/wh_8821 \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"isActive": false}'
```

`url`, `events`, `description`, `isActive` and `maxRetries` can all be changed. Setting `isActive: false` pauses deliveries without losing the subscription or its secret — the right move during a deploy, rather than deleting and recreating.

## Delete

```bash
curl -X DELETE https://app.limecall.com/api/v1/webhooks/wh_8821 \
  -H "Authorization: Bearer sk_live_..."
```

Permanent, and the secret goes with it.

## Choosing maxRetries

Retries cover a brief outage on your side. They do not fix an endpoint that returns an error for a payload it cannot handle — that will exhaust its retries and be dropped.

Return `2xx` as soon as you have accepted the payload and process asynchronously, so a slow database does not turn into a retry storm.