> ## 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

> Get notified on your server when push is sent, delivered, clicked, fails, or is cancelled.

<Tip>
  With the API you **ask**; with webhooks Notifique **tells you**. Great for tracking delivery, measuring clicks, or removing devices with invalid subscriptions, without polling.
</Tip>

## In brief

* Every delivery is a **POST** `application/json` to your registered URL.
* `push.*` events are **push only**, WhatsApp uses `message.*`, SMS uses `sms.*`.
* `instanceId` is **empty** (push does not use a channel instance).
* Enable **only** the events your integration needs.
* Respond **2xx quickly**; heavy processing goes to your queue.

General setup: [Webhooks](/en/guides/webhooks/index). Security (HMAC signature): [Webhook security](/en/guides/webhooks/seguranca).

***

## How the POST looks

```json theme={null}
{
  "event": "push.delivered",
  "workspaceId": "clxx123...",
  "instanceId": "",
  "timestamp": "2025-02-10T14:30:00.000Z",
  "data": {
    "pushId": "clxx456...",
    "deviceId": "clxx789...",
    "appId": "clxxabc...",
    "status": "DELIVERED",
    "deliveredAt": "2025-02-10T14:30:05.000Z"
  }
}
```

| Field         | Description                                                 |
| ------------- | ----------------------------------------------------------- |
| `event`       | Event name (e.g. `push.delivered`)                          |
| `workspaceId` | Workspace ID                                                |
| `instanceId`  | Always empty for push                                       |
| `timestamp`   | ISO 8601, use for anti-replay                               |
| `data`        | Send fields (`pushId`, `deviceId`, `appId`, `status`, etc.) |

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

| Event            | When it fires                      | What to do with it      |
| ---------------- | ---------------------------------- | ----------------------- |
| `push.sent`      | Push accepted and sent to provider | Mark as sent            |
| `push.delivered` | Device confirmed delivery          | Delivery metrics        |
| `push.clicked`   | User opened the notification       | Deep link, conversion   |
| `push.failed`    | Invalid subscription or error      | Remove or update device |
| `push.cancelled` | Schedule cancelled before send     | Update queue            |

***

## Payload per event

<AccordionGroup>
  <Accordion title="push.sent">
    ```json theme={null}
    {
      "event": "push.sent",
      "workspaceId": "clxx123...",
      "instanceId": "",
      "timestamp": "2025-02-10T14:29:00.000Z",
      "data": {
        "pushId": "clxx456...",
        "deviceId": "clxx789...",
        "appId": "clxxabc...",
        "status": "SENT",
        "title": "Hello!",
        "sentAt": "2025-02-10T14:29:00.000Z"
      }
    }
    ```
  </Accordion>

  <Accordion title="push.delivered">
    Fires when the **service worker** or client reports delivery.

    ```json theme={null}
    {
      "event": "push.delivered",
      "workspaceId": "clxx123...",
      "instanceId": "",
      "timestamp": "2025-02-10T14:30:00.000Z",
      "data": {
        "pushId": "clxx456...",
        "deviceId": "clxx789...",
        "appId": "clxxabc...",
        "status": "DELIVERED",
        "deliveredAt": "2025-02-10T14:30:05.000Z"
      }
    }
    ```
  </Accordion>

  <Accordion title="push.clicked">
    ```json theme={null}
    {
      "event": "push.clicked",
      "workspaceId": "clxx123...",
      "instanceId": "",
      "timestamp": "2025-02-10T14:35:00.000Z",
      "data": {
        "pushId": "clxx456...",
        "deviceId": "clxx789...",
        "appId": "clxxabc...",
        "status": "CLICKED",
        "clickedAt": "2025-02-10T14:35:00.000Z",
        "url": "https://yoursite.com/notifications"
      }
    }
    ```
  </Accordion>

  <Accordion title="push.failed">
    Best practice: deactivate or remove the **deviceId** on invalid subscription.

    ```json theme={null}
    {
      "event": "push.failed",
      "workspaceId": "clxx123...",
      "instanceId": "",
      "timestamp": "2025-02-10T14:29:30.000Z",
      "data": {
        "pushId": "clxx456...",
        "deviceId": "clxx789...",
        "appId": "clxxabc...",
        "status": "FAILED",
        "failedAt": "2025-02-10T14:29:30.000Z",
        "errorMessage": "subscription_expired"
      }
    }
    ```
  </Accordion>

  <Accordion title="push.cancelled">
    ```json theme={null}
    {
      "event": "push.cancelled",
      "workspaceId": "clxx123...",
      "instanceId": "",
      "timestamp": "2025-02-10T12:00:00.000Z",
      "data": {
        "pushId": "clxx456...",
        "deviceId": "clxx789...",
        "appId": "clxxabc...",
        "status": "CANCELLED"
      }
    }
    ```
  </Accordion>
</AccordionGroup>

***

## Next steps

* [Quick Start](/en/push-api/como-funciona/quick-start): app → device → send
* [Introduction](/en/push-api/como-funciona/introducao): status lifecycle
* [Scopes](/en/push-api/como-funciona/escopos-da-api-key): key permissions
* [Webhooks (general guide)](/en/guides/webhooks/index)