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

# Webhook Events

> Receive on your server when an automation changes status or when a run starts, completes, fails, or is cancelled.

<Tip>
  With the API you **ask**; with webhooks Notifique **notifies**. Ideal for pausing external campaigns, opening support tickets, or auditing runs without polling.
</Tip>

## In short

* Every delivery is a **POST** with `application/json` to your registered URL.
* `automation.*` events cover the **definition** (enable/disable) and **runs** (executions).
* `instanceId` is **empty** (automations belong to the workspace, not a channel).
* Enable **only** the events your integration uses.
* Respond **2xx quickly**; heavy processing goes to a queue on your side.

General setup: [Webhooks](/guides/webhooks/index).

<Note>
  This is an **outbound** webhook (Notifique → your server). To **trigger** an automation with a POST from your system, configure the HTTP trigger in the automation editor or use [Events](/automations-api/como-funciona/eventos).
</Note>

***

## How the POST looks

```json theme={null}
{
  "event": "automation.run.completed",
  "workspaceId": "clxx123...",
  "instanceId": "",
  "timestamp": "2026-07-25T16:05:00.000Z",
  "data": {
    "automationId": "clxx...",
    "runId": "clxx...",
    "contactId": "clxx...",
    "status": "COMPLETED",
    "previousStatus": "RUNNING",
    "eventName": "whatsapp.inbound",
    "isSandbox": false,
    "errorMessage": null,
    "startedAt": "2026-07-25T16:04:50.000Z",
    "completedAt": "2026-07-25T16:05:00.000Z"
  }
}
```

| Field         | Description                                  |
| ------------- | -------------------------------------------- |
| `event`       | Event name (e.g. `automation.run.completed`) |
| `workspaceId` | Workspace ID                                 |
| `instanceId`  | Always empty for automations                 |
| `timestamp`   | ISO 8601, use for anti-replay                |
| `data`        | Definition or run fields                     |

Headers: `X-Notifique-Signature`, `X-Notifique-Timestamp`, `X-Workspace-Id`, `X-Webhook-Event`.

***

## What your server should return

| Response                | Effect                               |
| ----------------------- | ------------------------------------ |
| **2xx** within \~10s    | Event delivered; removed from queue  |
| **4xx / 5xx / timeout** | Automatic retry (5 min, 30 min, 2 h) |

<Note>
  Slow processing? Return **200** immediately and process in the background.
</Note>

***

## Event reference

### Automation definition

| Event                       | When it fires                     | What to do with it             |
| --------------------------- | --------------------------------- | ------------------------------ |
| `automation.enabled`        | Definition moves to `ENABLED`     | Enable the flow in your system |
| `automation.disabled`       | Definition moves to `DISABLED`    | Pause external dependencies    |
| `automation.status_changed` | Any `ENABLED` ↔ `DISABLED` change | Update status in CRM/ERP       |

### Run (execution)

| Event                      | When it fires                | What to do with it               |
| -------------------------- | ---------------------------- | -------------------------------- |
| `automation.run.started`   | A run is created and starts  | Open ticket / execution log      |
| `automation.run.completed` | Run finishes successfully    | Close flow / mark success        |
| `automation.run.failed`    | Run fails on a critical step | Alert and inspect `errorMessage` |
| `automation.run.cancelled` | Run cancelled (stop)         | Clear pending state              |

***

## Payload per event

<AccordionGroup>
  <Accordion title="automation.disabled">
    ```json theme={null}
    {
      "event": "automation.disabled",
      "workspaceId": "clxx...",
      "instanceId": "",
      "timestamp": "2026-07-25T16:00:00.000Z",
      "data": {
        "automationId": "clxx...",
        "name": "WhatsApp welcome",
        "status": "DISABLED",
        "previousStatus": "ENABLED",
        "triggerKind": "CHANNEL_INBOUND",
        "triggerChannel": "WHATSAPP",
        "triggerEventName": null,
        "graphVersion": 3
      }
    }
    ```
  </Accordion>

  <Accordion title="automation.run.completed">
    ```json theme={null}
    {
      "event": "automation.run.completed",
      "workspaceId": "clxx...",
      "instanceId": "",
      "timestamp": "2026-07-25T16:05:00.000Z",
      "data": {
        "automationId": "clxx...",
        "runId": "clxx...",
        "contactId": "clxx...",
        "status": "COMPLETED",
        "previousStatus": "RUNNING",
        "eventName": "whatsapp.inbound",
        "isSandbox": false,
        "errorMessage": null,
        "startedAt": "2026-07-25T16:04:50.000Z",
        "completedAt": "2026-07-25T16:05:00.000Z"
      }
    }
    ```
  </Accordion>
</AccordionGroup>

***

## Next steps

* [Introduction](/automations-api/como-funciona/introducao)
* [Events (API trigger)](/automations-api/como-funciona/eventos)
* [Webhooks](/guides/webhooks/index)