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

# Webhooks

# Webhooks

## Overview

Webhooks let your application receive real-time HTTP notifications when events occur in Animo (new submissions, lead changes, meeting bookings, etc.). Use the API to register, update, and remove webhook endpoints.

This documentation covers webhook **management** endpoints only (register, update, remove). Event delivery is handled by Animo when events occur.

## Prerequisites

* Company subscription must include `USE_INTEGRATIONS`.
* Token must include at least one `*:subscribe` scope matching the events you want to receive.

## Webhook events

| Event value            | Scope required          | Description               |
| ---------------------- | ----------------------- | ------------------------- |
| `activation-submitted` | `activations:subscribe` | New activation submission |
| `form-submitted`       | `submissions:subscribe` | New form submission       |
| `lead-created`         | `leads:subscribe`       | Lead created              |
| `lead-updated`         | `leads:subscribe`       | Lead updated              |
| `lead-deleted`         | `leads:subscribe`       | Lead deleted              |
| `meeting-booked`       | `meetings:subscribe`    | Meeting booked            |
| `meeting-updated`      | `meetings:subscribe`    | Meeting updated           |
| `meeting-cancelled`    | `meetings:subscribe`    | Meeting cancelled         |

You can only subscribe to events permitted by the subscribe scopes on your token.

## Endpoints

### Attach webhook

* **Method:** `POST`
* **Path:** `/api/v1/{company}/webhooks/attach`
* **Scope:** At least one of `activations:subscribe`, `submissions:subscribe`, `leads:subscribe`, `meetings:subscribe`
* **Subscription:** `USE_INTEGRATIONS`

#### Request body

```json theme={null}
{
  "name": "My integration",
  "url": "https://example.com/webhooks/animo",
  "events": [
    "activation-submitted",
    "lead-created",
    "form-submitted"
  ]
}
```

| Field    | Required | Description                                                  |
| -------- | -------- | ------------------------------------------------------------ |
| `name`   | Yes      | Unique name per user (max 255 chars)                         |
| `url`    | Yes      | HTTPS callback URL (max 255 chars)                           |
| `events` | Yes      | Array of webhook event values (must match your token scopes) |

#### Response `201`

```json theme={null}
{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "My integration",
    "token": "random32charSecretToken...",
    "url": "https://example.com/webhooks/animo",
    "events": [
      "activation-submitted",
      "lead-created",
      "form-submitted"
    ],
    "created_at": "2026-06-01T12:00:00.000+00:00"
  }
}
```

Store the `token` securely — it is required to update or detach the webhook.

#### Response fields

| Field        | Type   | Description                    |
| ------------ | ------ | ------------------------------ |
| `id`         | string | Webhook UUID                   |
| `name`       | string | Webhook name                   |
| `token`      | string | Secret token for update/detach |
| `url`        | string | Callback URL                   |
| `events`     | array  | Subscribed event values        |
| `created_at` | string | ISO 8601 timestamp             |

***

### Update webhook

* **Method:** `PATCH`
* **Path:** `/api/v1/{company}/webhooks/update`
* **Scope:** Matching subscribe scope(s) for any events being set
* **Subscription:** `USE_INTEGRATIONS`

#### Request body

At least one of `name`, `url`, or `events` must be provided (along with `id` and `token`).

```json theme={null}
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "token": "random32charSecretToken...",
  "url": "https://example.com/webhooks/animo-v2"
}
```

| Field    | Required | Description                       |
| -------- | -------- | --------------------------------- |
| `id`     | Yes      | Webhook UUID                      |
| `token`  | Yes      | Secret token from attach response |
| `name`   | No       | New name                          |
| `url`    | No       | New HTTPS URL                     |
| `events` | No       | New event array                   |

#### Response `200`

Returns the updated `WebhookResource`.

#### Errors

| Status | When                                |
| ------ | ----------------------------------- |
| `422`  | Invalid token or validation failure |

***

### Detach webhook

* **Method:** `DELETE`
* **Path:** `/api/v1/{company}/webhooks/detach`
* **Scope:** Any subscribe scope (token must be valid)
* **Subscription:** `USE_INTEGRATIONS`

#### Request body

```json theme={null}
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "token": "random32charSecretToken..."
}
```

#### Response `204`

Empty body on success.

## Related

* [Authentication](../authentication.md)
* [Conventions](../conventions.md)
* [Activations](activations.md)
* [Forms](forms.md)