# Webhooks

## List webhooks

`GET /v1/c/{slug}/webhooks` · Scopes: `webhooks:manage`

### Path parameters

| Field | Notes |
|---|---|
| `slug` | The company's identifier in DoneTalk (the key's own). |

### Request example

```bash
curl -X GET "https://api.donetalk.com/v1/c/demo/webhooks" \
  -H "Authorization: Bearer $DONETALK_KEY"
```

### Response 200

```json
{
  "webhooks": [
    {
      "id": "01a0cb03-417a-7da4-9ae2-70bc321eeef5",
      "url": "https://erp.captei.com.br/donetalk/avisos",
      "events": [
        "campaign.completed",
        "campaign.recipient.replied",
        "conversation.closed"
      ],
      "status": "active",
      "failureCount": 0,
      "createdBy": null,
      "createdAt": "2026-10-23T13:02:11.000Z",
      "updatedAt": "2026-10-23T13:02:11.000Z"
    }
  ]
}
```

### Possible errors

- `401` `unauthorized`
- `403` `insufficient_scope`
- `422` `validation_failed`
- `429` `rate_limited`

## Create a webhook

`POST /v1/c/{slug}/webhooks` · Scopes: `webhooks:manage`

An address of your system and the events it receives. The `secret` comes back only once: keep it to check the signatures.

### Path parameters

| Field | Notes |
|---|---|
| `slug` | The company's identifier in DoneTalk (the key's own). |

### Request body

| Field | Type | Required | Notes |
|---|---|---|---|
| `url` | string (uri) | yes | up to 2000 characters |
| `events` | list of one of `conversation.opened`, `conversation.closed`, `conversation.assigned`, `conversation.transferred`, `conversation.reopened`, `contact.updated`, `contact.consent_changed`, `message.received`, `message.sent`, `message.delivered`, `message.read`, `message.failed`, `flow.event`, `appointment.booked`, `appointment.rescheduled`, `appointment.cancelled`, `appointment.confirmed`, `appointment.attended`, `appointment.no_show`, `campaign.started`, `campaign.paused`, `campaign.resumed`, `campaign.completed`, `campaign.cancelled`, `campaign.recipient.sent`, `campaign.recipient.delivered`, `campaign.recipient.read`, `campaign.recipient.replied`, `campaign.recipient.failed`, `campaign.recipient.opted_out` | yes | up to 30 |

### Request example

```bash
curl -X POST "https://api.donetalk.com/v1/c/demo/webhooks" \
  -H "Authorization: Bearer $DONETALK_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://erp.captei.com.br/donetalk/avisos",
  "events": [
    "campaign.completed",
    "campaign.recipient.replied",
    "conversation.closed"
  ]
}'
```

### Response 201

```json
{
  "webhook": {
    "id": "01a0cb03-417a-7da4-9ae2-70bc321eeef5",
    "url": "https://erp.captei.com.br/donetalk/avisos",
    "events": [
      "campaign.completed",
      "campaign.recipient.replied",
      "conversation.closed"
    ],
    "status": "active",
    "failureCount": 0,
    "createdBy": null,
    "createdAt": "2026-10-23T13:02:11.000Z",
    "updatedAt": "2026-10-23T13:02:11.000Z"
  },
  "secret": "dsf_whsec_4Jx…"
}
```

### Possible errors

- `401` `unauthorized`
- `403` `insufficient_scope`
- `422` `validation_failed`
- `429` `rate_limited`

## Edit a webhook

`PATCH /v1/c/{slug}/webhooks/{id}` · Scopes: `webhooks:manage`

### Path parameters

| Field | Notes |
|---|---|
| `slug` | The company's identifier in DoneTalk (the key's own). |
| `id` | The record's id. |

### Request body

| Field | Type | Required | Notes |
|---|---|---|---|
| `url` | string (uri) | no | up to 2000 characters |
| `events` | list of one of `conversation.opened`, `conversation.closed`, `conversation.assigned`, `conversation.transferred`, `conversation.reopened`, `contact.updated`, `contact.consent_changed`, `message.received`, `message.sent`, `message.delivered`, `message.read`, `message.failed`, `flow.event`, `appointment.booked`, `appointment.rescheduled`, `appointment.cancelled`, `appointment.confirmed`, `appointment.attended`, `appointment.no_show`, `campaign.started`, `campaign.paused`, `campaign.resumed`, `campaign.completed`, `campaign.cancelled`, `campaign.recipient.sent`, `campaign.recipient.delivered`, `campaign.recipient.read`, `campaign.recipient.replied`, `campaign.recipient.failed`, `campaign.recipient.opted_out` | no | up to 30 |
| `status` | one of `active`, `paused` | no |  |

### Request example

```bash
curl -X PATCH "https://api.donetalk.com/v1/c/demo/webhooks/:id" \
  -H "Authorization: Bearer $DONETALK_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "status": "paused"
}'
```

### Response 200

```json
{
  "webhook": {
    "id": "01a0cb03-417a-7da4-9ae2-70bc321eeef5",
    "url": "https://erp.captei.com.br/donetalk/avisos",
    "events": [
      "campaign.completed",
      "campaign.recipient.replied",
      "conversation.closed"
    ],
    "status": "active",
    "failureCount": 0,
    "createdBy": null,
    "createdAt": "2026-10-23T13:02:11.000Z",
    "updatedAt": "2026-10-23T13:02:11.000Z"
  }
}
```

### Possible errors

- `401` `unauthorized`
- `403` `insufficient_scope`
- `422` `validation_failed`
- `429` `rate_limited`

## Delete a webhook

`DELETE /v1/c/{slug}/webhooks/{id}` · Scopes: `webhooks:manage`

### Path parameters

| Field | Notes |
|---|---|
| `slug` | The company's identifier in DoneTalk (the key's own). |
| `id` | The record's id. |

### Request example

```bash
curl -X DELETE "https://api.donetalk.com/v1/c/demo/webhooks/:id" \
  -H "Authorization: Bearer $DONETALK_KEY"
```

### Response 200

```json
{
  "ok": true
}
```

### Possible errors

- `401` `unauthorized`
- `403` `insufficient_scope`
- `422` `validation_failed`
- `429` `rate_limited`

## Send a test event

`POST /v1/c/{slug}/webhooks/{id}/test` · Scopes: `webhooks:manage`

### Path parameters

| Field | Notes |
|---|---|
| `slug` | The company's identifier in DoneTalk (the key's own). |
| `id` | The record's id. |

### Request example

```bash
curl -X POST "https://api.donetalk.com/v1/c/demo/webhooks/:id/test" \
  -H "Authorization: Bearer $DONETALK_KEY"
```

### Response 202

```json
{
  "deliveryId": "01a3e4f5-a6b7-7c8d-9e0f-1a2b3c4d5e6f",
  "eventId": "01a3c0de-8b22-7c33-9d44-0e55f6677889"
}
```

### Possible errors

- `401` `unauthorized`
- `403` `insufficient_scope`
- `422` `validation_failed`
- `429` `rate_limited`

## Recent deliveries

`GET /v1/c/{slug}/webhooks/{id}/deliveries` · Scopes: `webhooks:manage`

### Path parameters

| Field | Notes |
|---|---|
| `slug` | The company's identifier in DoneTalk (the key's own). |
| `id` | The record's id. |

### Request example

```bash
curl -X GET "https://api.donetalk.com/v1/c/demo/webhooks/:id/deliveries" \
  -H "Authorization: Bearer $DONETALK_KEY"
```

### Response 200

```json
{
  "deliveries": [
    {
      "id": "01a3e4f5-a6b7-7c8d-9e0f-1a2b3c4d5e6f",
      "eventId": "01a3c0de-8b22-7c33-9d44-0e55f6677889",
      "eventType": "campaign.recipient.replied",
      "attempt": 1,
      "status": "delivered",
      "responseCode": 200,
      "responseMs": 84,
      "nextAttemptAt": null,
      "createdAt": "2026-10-24T12:04:03.000Z"
    }
  ]
}
```

### Possible errors

- `401` `unauthorized`
- `403` `insufficient_scope`
- `422` `validation_failed`
- `429` `rate_limited`