Documentation
Sign inGet started
Get started
Guides
API Reference
SDKs
CLI
Knowledge Base
Changelog

Test a webhook with a sample event

POST
/v1/webhooks/{webhook_id}/test
bird webhooks test <webhook-id> --event-type email.delivered
Response200
{
  "status": "delivered",
  "response_status_code": 200,
  "response_body": "OK",
  "response_duration_ms": 142,
  "event_payload": {
    "type": "domain.failed",
    "timestamp": "2026-05-21T12:00:00Z",
    "data": {
      "domain_id": "dom_01krdgeqcxet5s7t44vh8rt9mg",
      "domain": "mail.example.com",
      "workspace_id": "ws_01krdgeqcxet5s7t44vh8rt9mg",
      "failure_reason": "DKIM record not found at the expected selector."
    }
  },
  "error": "connection refused"
}
Sends a signed synthetic event and returns whether your endpoint accepted it, its HTTP status, and the round-trip latency. An unreachable endpoint returns status: failed in the response body. The endpoint has 10 seconds to respond.
The body is a minimal JSON object with the event type, signed like a real delivery. It does not mirror that event's payload. Tests work on paused endpoints and do not appear in List delivery attempts.
The operation returns 412 if the endpoint lacks a valid signing secret or, when event_type is omitted, has no subscribed event type to use.
Parameters
webhook_id
string
ID of the webhook endpoint (whk_ prefix), as returned when it was created.
Request Payload
event_type
string
Event type to simulate. Any type from the event catalog is accepted, whether or not the endpoint subscribes to it; an unknown type returns a 422. When omitted, the endpoint's first subscribed event type is used.
Response Payload
status
string
required
Whether your endpoint accepted the test event. delivered means it returned a 2xx status; failed means it returned a non-2xx status or could not be reached (see error for the latter).
Possible values: delivered, failed
response_status_code
nullable integer
required
HTTP status returned by your endpoint. Null when no response was received (timeout, connection error, DNS failure).
response_body
string
Response body returned by your endpoint, truncated to the first 1024 bytes. Omitted when your endpoint returned no body or could not be reached.
response_duration_ms
integer
required
Round-trip delivery latency in milliseconds.
event_payload
object
The full event body delivered to your endpoint. Test sends use a minimal synthetic body rather than a full event payload, so this field is omitted.
Show child attributes
event_payload.type
string
required
Event type.
Possible values: whatsapp.sent
event_payload.timestamp
string
required
Time the API handed the message to Meta for delivery.
event_payload.data
object
required
Payload of the whatsapp.sent event.
Show child attributes
event_payload.data.whatsapp_id
string
required
ID of the WhatsApp message.
event_payload.data.workspace_id
string
required
ID of the workspace that owns this event.
event_payload.data.direction
string
required
Whether the message was sent by the business (outbound) or received from the contact (inbound).
Possible values: outbound, inbound
event_payload.data.from
object
required
Sender of the message. On outbound messages, the business number it was sent from; on inbound, the WhatsApp contact.
Show child attributes
event_payload.data.from.phone_number
string
Phone number in E.164 format, when known.
event_payload.data.from.bsuid
string
Business-scoped user ID, Meta's identifier for the WhatsApp user. Present only on the WhatsApp-user side of the message.
event_payload.data.to
object
required
Recipient of the message. On outbound messages, the WhatsApp contact; on inbound, the business number.
Show child attributes
event_payload.data.to.phone_number
string
Phone number in E.164 format, when known.
event_payload.data.to.bsuid
string
Business-scoped user ID, Meta's identifier for the WhatsApp user. Present only on the WhatsApp-user side of the message.
event_payload.data.tags
nullable array
required
Tags provided on the send request, echoed on every event for the message. Null when the message carried no tags.
event_payload.data.metadata
nullable object
required
The metadata object provided on the send request, echoed on every event for the message. Null when the message carried no metadata.
error
string
A short explanation of why the event could not be delivered. Present only when your endpoint could not be reached.