Webhooks

Get a webhook delivery

One delivery, including the exact payload that was signed and sent.

get/v1/projects/{project_id}/webhook-deliveries/{delivery_id}

Request

  • Base URL: https://api.naturali.ai
  • URL: https://api.naturali.ai/v1/projects/{project_id}/webhook-deliveries/{delivery_id}
  • Auth: one of:
    • HTTP bearer
    • OAuth 2 (authorization code, authorization URL https://api.naturali.ai/authorize, token URL https://api.naturali.ai/token, scopes: mcp:access)

Response

The delivery.

idstring required

Public delivery ID (whd_ prefix). Sent with the request as X-Naturali-Delivery.

project_idstring required
webhook_idstring required
event_idstring required

The event's id; shared by every delivery and redelivery of it.

type'conversation.started' | 'message.received' | 'generation.completed' | 'generation.failed' | 'usage.threshold_crossed' | 'project.paused' | 'project.resumed' | 'decision.completed' | 'decision.failed' | 'task.created' | 'task.transitioned' | 'task.closed' | 'task.migrated' | 'task.stalled' | 'task.paused' | 'task.resumed' | 'task.approval_failed' | 'task.automation_retrying' | 'task.automation_rejected' | 'task.automation_unrouted' | 'approval.created' | 'approval.approved' | 'approval.rejected' | 'approval.expired' required

A naturali event type. The set below is what this API emits — deliberately only the events it can itself cause, so no declared name is one that never fires. It grows as modules land.

status'pending' | 'success' | 'failed' required

pending until a 2xx is received (success) or the attempts are exhausted (failed). A failed delivery can be replayed with …:redeliver.

status_codeinteger nullable required

The receiver's HTTP status on the last attempt; null when the attempt never got a response (DNS, TLS, refused, timed out).

attemptsinteger required

Attempts made so far.

next_attempt_atstring date-time nullable required

When the next retry is due; null once the delivery is terminal.

last_attempt_atstring date-time nullable required
response_bodystring nullable required

A truncated snippet of the receiver's response, or the transport error when there was no response.

created_atstring date-time required
updated_atstring date-time required

Example response

{
  "id": "whd_V1StGXR8Z5jdHi6B",
  "project_id": "proj_V1StGXR8Z5jdHi6B",
  "webhook_id": "whk_V1StGXR8Z5jdHi6B",
  "event_id": "evt_V1StGXR8Z5jdHi6B",
  "type": "conversation.started",
  "payload": {
    "id": "evt_V1StGXR8Z5jdHi6B",
    "type": "conversation.started",
    "project_id": "proj_V1StGXR8Z5jdHi6B",
    "resource_type": "conversation",
    "resource_id": "conv_V1StGXR8Z5jdHi6B",
    "created_at": "2026-07-31T00:00:00.000Z"
  },
  "status": "success",
  "status_code": 200,
  "attempts": 1,
  "last_attempt_at": "2026-07-31T00:00:01.000Z",
  "response_body": "ok",
  "created_at": "2026-07-31T00:00:00.000Z",
  "updated_at": "2026-07-31T00:00:01.000Z"
}

Changes

No recorded changes to this operation across all 1 revision of this API.