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

# Webhooks overview

> Subscribe to organization events and receive signed HTTP callbacks.

Outbound webhooks let your system react to changes inside Notealy without polling. Configure a subscription URL in **Settings → Webhooks**, and Notealy will POST a signed JSON envelope every time a matching event occurs.

## Envelope

```json theme={null}
{
  "id": "evt_01J...",
  "type": "contact.tag_added",
  "created": "2026-05-04T18:21:00.000Z",
  "api_version": "1",
  "data": {
    "contactId": "01J...",
    "tagId": "01J...",
    "tagName": "web-lead",
    "organizationId": "01J..."
  }
}
```

Headers:

| Header                  | Purpose                                           |
| ----------------------- | ------------------------------------------------- |
| `X-Notealy-Delivery-Id` | Unique per delivery attempt                       |
| `X-Notealy-Event-Type`  | Same as `type` in the body, for cheap routing     |
| `X-Notealy-Signature`   | HMAC signature — see [Signing](/webhooks/signing) |
| `User-Agent`            | `Notealy-Webhooks/1`                              |

## Available events

| Event                   | When it fires                                                  |
| ----------------------- | -------------------------------------------------------------- |
| `contact.created`       | A new contact is created (any source — UI, public API, import) |
| `contact.stage_changed` | A contact moves between pipeline stages                        |
| `contact.assigned`      | A contact is assigned to a user                                |
| `deal.created`          | A new deal is created                                          |
| `deal.updated`          | A deal's fields are updated                                    |
| `deal.won`              | A deal is moved to a `WON` stage                               |
| `deal.lost`             | A deal is moved to a `LOST` stage                              |
| `message.sent`          | A message is sent (any channel)                                |
| `message.received`      | A message is received (any channel)                            |

Subscriptions accept either a specific list of event types or `*` for all events.

## Responding

Return any 2xx within 25 seconds. Anything else (including timeouts) is treated as failure and triggers retries — see [Retries](/webhooks/retries).

Treat webhooks as **at-least-once**: Notealy may deliver the same event more than once on retry. Use `X-Notealy-Delivery-Id` to deduplicate on your side.