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

# Worked request and response samples

> Worked samples for the most-used webhook operations: register an endpoint, read deliveries, and replay one. Each sample shows the request, the success envelope, and the error envelope to expect.

## Worked request and response samples

Copy a request body as written, substitute your own ids, and compare the response envelope. Errors follow Devotel Orbit's `{ error, meta }` envelope, shown once below under **Error envelope**.

### Create a webhook endpoint

<Note>
  `POST /api/v1/webhooks/`
</Note>

The body needs at least one subscribed event. Subscribe only the events you plan to consume — a broad `["*"]` receiver is harder to debug and racy.

**Request**

```json theme={null}
{
  "url": "https://receiver.example.dev/webhooks",
  "events": ["message.delivered", "message.failed"],
  "description": "Project delivery notifications"
}
```

<ResponseExample>
  ```json 201 theme={null}
  {
    "data": {
      "id": "wh_5f8a1c2d7a4b9e02c3d4e5f6",
      "url": "https://receiver.example.dev/webhooks",
      "events": ["message.delivered", "message.failed"],
      "status": "active"
    },
    "meta": {
      "request_id": "req_webhook",
      "timestamp": "2026-08-01T12:00:00.000Z"
    }
  }
  ```
</ResponseExample>

### List outgoing deliveries for an endpoint

<Note>
  `GET /api/v1/webhooks/deliveries`
</Note>

<ParamField query="endpoint_id" type="string">
  Restrict to one webhook endpoint id.
</ParamField>

<ParamField query="status" type="string">
  e.g. `delivered`, `failed`, `pending`.
</ParamField>

<ResponseExample>
  ```json 200 theme={null}
  {
    "data": [
      {
        "id": "del_7c4e2a9b1d3f50618293a4b5",
        "event": "message.delivered",
        "status": "failed",
        "response_code": 502
      }
    ],
    "meta": {
      "request_id": "req_deliveries",
      "timestamp": "2026-08-01T12:01:00.000Z"
    }
  }
  ```
</ResponseExample>

### Replay a delivery

<Note>
  `POST /api/v1/webhooks/dlq/{delivery_id}/replay`
</Note>

Redispatches a delivery whose previous attempt failed, without changing subscriptions.

<ResponseExample>
  ```json 200 theme={null}
  {
    "data": {
      "id": "del_7c4e2a9b1d3f50618293a4b5",
      "status": "replayed"
    },
    "meta": {
      "request_id": "req_replay",
      "timestamp": "2026-08-01T12:02:00.000Z"
    }
  }
  ```
</ResponseExample>

### Error envelope

```json 422 theme={null}
{
  "error": {
    "code": "VALIDATION_ERROR",
    "status": 422,
    "message": "events: subscribe to at least one event"
  },
  "meta": {
    "request_id": "req_...",
    "timestamp": "2026-08-01T12:00:00.000Z"
  }
}
```