---
title: "Webhooks"
description: "Register, list and test outgoing webhook endpoints for publish events."
section: "API reference"
url: https://dravo.dev/docs/api/webhooks
---
# Webhooks

These endpoints configure outgoing webhooks and use the dashboard JWT. For the
payload shape and signature verification, see [webhooks](/docs/concepts/webhooks).

## List endpoints

#### `GET /v1/webhooks`

List your registered outgoing webhook endpoints.

**Auth:** Dashboard JWT only

Response `200`: Endpoints.

```json
[
  {
    "id": "wh_1",
    "url": "https://example.com/hook",
    "events": [
      "post.published"
    ],
    "active": true
  }
]
```


## Register an endpoint

The signing secret is returned once at creation. Use it to verify the
`Dravo-Signature` header on every delivery.

#### `POST /v1/webhooks`

Register a webhook endpoint. The signing secret is shown once.

**Auth:** Dashboard JWT only

| Field | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `url` | body | string (URL) | yes | Endpoint that will receive events. |
| `events` | body | string[] | yes | post.published, post.failed, post.queued or connection.revoked (at least one). |

Request:

```json
{
  "url": "https://example.com/hook",
  "events": [
    "post.published",
    "post.failed"
  ]
}
```

Response `201`: Created (secret shown once).

```json
{
  "id": "wh_1",
  "url": "https://example.com/hook",
  "events": [
    "post.published",
    "post.failed"
  ],
  "signing_secret": "whsec_…"
}
```


## Test an endpoint

Send a sample event and inspect the delivery result.

#### `POST /v1/webhooks/{webhook_id}/test`

Send a test event to a webhook endpoint and return the delivery result.

**Auth:** Dashboard JWT only

| Field | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `webhook_id` | path | string | yes | Endpoint to test. |

Response `200`: Delivery result.

```json
{
  "id": "del_1",
  "event_type": "post.published",
  "status_code": 200,
  "attempts": 1
}
```