# Overview

Webhooks allow you to receive real-time notifications when events occur in your Aktify campaigns. When you register a webhook, Aktify sends HTTP POST requests to your URL whenever specific events happen.

To set up a webhook, contact your account executive or configure it through the Aktify Portal. You'll set up a **client secret** in the Portal that you'll use to verify webhook requests.

## Supported Events

### v1 Events (Legacy)

These events are currently live in production.

| Event | Description |
| :--- | :--- |
| [`dnc.created`](./legacy/lead-lifecycle-events#dnccreated) | A phone number was added to the Do Not Contact list |
| [`webchat.lead.created`](./legacy/webchat-events#webchatleadcreated) | A new lead was captured via WebChat |

### v2 Events

| Event | Category | Description |
| :--- | :--- | :--- |
| [`dnc.created`](./v2/lead-lifecycle-events#dnccreated) | Lead Lifecycle | A phone number was added to the Do Not Contact list |
| [`campaign.lead_created`](./v2/lead-lifecycle-events#campaignlead_created) | Lead Lifecycle | A new lead was posted to a campaign |
| [`lead.message_sent`](./v2/message-events#leadmessage_sent) | Messaging | An outbound SMS was sent to a lead |
| [`lead.message_received`](./v2/message-events#leadmessage_received) | Messaging | An inbound SMS was received from a lead |
| [`lead.message_delivered`](./v2/message-events#leadmessage_delivered) | Messaging | An outbound SMS was confirmed delivered |
| [`lead.conversation_started`](./v2/message-events#leadconversation_started) | Messaging | The first outbound message to a lead was confirmed delivered |
| [`lead.carrier_optout_received`](./v2/message-events#leadcarrier_optout_received) | Messaging | A lead sent a carrier opt-out keyword (STOP) |
| [`lead.carrier_optin_received`](./v2/message-events#leadcarrier_optin_received) | Messaging | A lead sent a carrier opt-in keyword (START) |
| [`lead.carrier_help_received`](./v2/message-events#leadcarrier_help_received) | Messaging | A lead sent a carrier help keyword (HELP) |
| [`lead.call_initiated`](./v2/call-events#leadcall_initiated) | Voice | An outbound call to a lead was initiated |
| [`lead.call_received`](./v2/call-events#leadcall_received) | Voice | An inbound call from a lead was received |
| [`lead.call_scheduled`](./v2/call-events#leadcall_scheduled) | Voice | A call requested by a lead was scheduled |
| [`lead.call_ended`](./v2/call-events#leadcall_ended) | Voice | A call with a lead ended |
| [`lead.call_transferred`](./v2/call-events#leadcall_transferred) | Voice | A call was transferred to an agent |
| [`lead.call_key_pressed`](./v2/call-events#leadcall_key_pressed) | Voice | A lead pressed a key during an IVR call |
| [`lead.link_sent`](./v2/link-events#leadlink_sent) | Links | An outbound SMS containing a URL was sent |
| [`lead.link_delivered`](./v2/link-events#leadlink_delivered) | Links | An outbound SMS containing a campaign link was confirmed delivered |
| [`lead.link_clicked`](./v2/link-events#leadlink_clicked) | Links | A lead clicked a tracked link |

## v1 Request Format (Legacy Events)

When an event occurs, Aktify sends a POST request to your registered webhook URL.

### Headers

```
aktify-signature: t=1638470400000,v1=5d41402abc4b2a76b9719d911017c592
```

### Body

```json
{
  "apiVersion": "2021-08-23",
  "type": "dnc.created",
  "data": {
    // Event-specific fields
  }
}
```

| Field | Type | Description |
| :--- | :--- | :--- |
| `apiVersion` | string | API version (currently `2021-08-23`) |
| `type` | string | The event type |
| `data` | object | Event-specific payload (see event pages for details) |
| `customData` | object? | Optional custom key-value pairs (WebChat only) |

## v2 Request Format

### Headers

```
aktify-signature: t=1706443200000,v2=a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2
```

:::info Signature Change
v2 events use a `v2` signature where the timestamp is included in the HMAC input. See [Verifying Requests](./verification) for details.
:::

### Body

```json
{
  "metadata": {
    "apiVersion": "2026-02-09",
    "eventType": "lead.message_sent",
    "campaignId": "abc456xyz",
    "eventTime": "2024-01-28T12:00:00.000Z"
  },
  "data": {
    // Event-specific fields
  }
}
```

| Field | Type | Description |
| :--- | :--- | :--- |
| `metadata.apiVersion` | string | API version (currently `2026-02-09`) |
| `metadata.eventType` | string | The event type |
| `metadata.campaignId` | string | The campaign ID associated with this event |
| `metadata.eventTime` | string | ISO 8601 timestamp of when the event occurred |
| `data` | object | Event-specific payload (see event pages for details) |