Sign inGet Started
Mulai sekarang
Panduan
Referensi API
SDK
CLI
Basis Pengetahuan
Changelog

Test a webhook with a sample event

POST
/v1/webhooks/{webhook_id}/test
const result = await bird.webhooks.test("whk_01krdgeqcxet5s7t44vh8rt9mg", {
  event_type: "email.delivered",
});
console.log(result.status);
Respons200
{
  "status": "delivered",
  "response_status_code": 200,
  "response_body": "OK",
  "response_duration_ms": 142,
  "event_payload": {
    "type": "amb.accepted",
    "timestamp": "2026-09-25T12:00:00Z",
    "data": {
      "workspace_id": "ws_01krdgeqcxet5s7t44vh8rt9mg",
      "message": {
        "id": "amb_01krdgeqcxet5s7t44vh8rt9mg",
        "conversation_id": "acv_01krdgeqcxet5s7t44vh8rt9mg",
        "business_id": "abz_01krdgeqcxet5s7t44vh8rt9mg",
        "direction": "outbound",
        "status": "accepted",
        "kind": "text",
        "source": "operator",
        "in_reply_to_message_id": "amb_01krdgeqcxet5s7t44vh8rt9mg",
        "locale": "en_US",
        "category": "order_update",
        "tags": [
          {
            "name": "category",
            "value": "welcome"
          }
        ],
        "cost": {
          "amount": "0.00990",
          "currency_code": "USD",
          "transaction_amount": "0.00790",
          "passthrough_amount": "0.00200"
        },
        "last_error": {
          "code": "bird:business_not_registered",
          "description": "Apple refused the message with HTTP status 404."
        }
      }
    }
  },
  "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.
Parameter
webhook_id
string
ID of the webhook endpoint (whk_ prefix), as returned when it was created.
Payload Permintaan
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.
Payload Respons
status
string
wajib
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
wajib
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
wajib
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.
Tampilkan atribut turunan
Bird charged and accepted an outbound message for processing. This does not mean Apple received the message.
event_payload.type
string
wajib
Always amb.accepted for this event.
Possible values: amb.accepted
event_payload.timestamp
string
wajib
When this lifecycle event occurred, independent of webhook delivery time.
event_payload.data
object
wajib
The workspace and message snapshot at the time of the lifecycle event.
Tampilkan atribut turunan
event_payload.data.workspace_id
string
wajib
Workspace that owns this message.
event_payload.data.message
object
wajib
Message state when the event occurred. Later state changes do not alter this snapshot. Customer metadata is included when present; reserved Bird metadata is excluded.
Tampilkan atribut turunan
event_payload.data.message.id
string
wajib
ID of the message, assigned when it is accepted or received. Pass it as message_id to the get-message and list-events endpoints.
event_payload.data.message.conversation_id
string
wajib
The conversation this message belongs to.
event_payload.data.message.business_id
string
wajib
The business the message was sent from or received by.
event_payload.data.message.from
string
Apple business identifier on outbound messages, or the customer's opaque Apple identifier on inbound messages. Omitted when that address is unavailable on a historical record.
event_payload.data.message.to
string
Customer's opaque Apple identifier on outbound messages, or the Apple business identifier on inbound messages. Omitted when that address is unavailable on a historical record.
event_payload.data.message.direction
string
wajib
Whether a message was sent by the business or received from the customer:
  • outbound: A reply the business sent into the conversation.
  • inbound: A message the customer sent.
Possible values: outbound, inbound
event_payload.data.message.status
string
wajib
Send status:
  • accepted: Accepted and queued for delivery to Apple.
  • sent: Handed to Apple. There is no delivery or read receipt on this channel, so sent is the furthest an outbound message's status advances.
  • send_failed: Sending stopped because of a business or conversation restriction, a recipient opt-out, an Apple refusal, or exhausted attempts. An earlier attempt may have reached Apple if its response or the local record of success was lost. See last_error for why sending stopped.
  • rejected: Refused by Bird before any send attempt and never charged: the destination has no price, the wallet could not fund the send, or the content cannot be sent yet. See last_error.
  • received: Received as an inbound message.
Possible values: accepted, sent, send_failed, rejected, received
event_payload.data.message.kind
string
wajib
Derived content classification for filtering and statistics.
Possible values: text, attachment, rich_link, quick_reply, list_picker, time_picker, form, apple_pay, authenticate, imessage_app, interactive
event_payload.data.message.source
string
Who sent this message. Absent on an inbound message, which has no source to report.
Possible values: operator, automation, api
event_payload.data.message.content
object
wajib
Native message content. Outgoing interactions contain requests; incoming interactions contain replies.
Tampilkan atribut turunan
event_payload.data.message.content.type
string
wajib
Always text.
Value: text
event_payload.data.message.content.body
string
Text displayed in the message. Use one U+FFFC object replacement character per attachment to control placement.
event_payload.data.message.content.subject
string
Subject displayed above the message body.
event_payload.data.message.content.attachments
array
Ordered attachments. Each object supplies a source URL or an encrypted Apple reference.
Tampilkan atribut turunan
event_payload.data.message.content.attachments.source_url
string
wajib
HTTPS URL Bird downloads and uploads to Apple.
event_payload.data.message.content.attachments.name
string
Display filename.
event_payload.data.message.content.attachments.mime_type
string
Media type of the attachment.
event_payload.data.message.content.rich_link_data
object
Tampilkan atribut turunan
event_payload.data.message.content.rich_link_data.url
string
wajib
HTTPS URL opened by the preview.
event_payload.data.message.content.rich_link_data.title
string
wajib
Preview title.
event_payload.data.message.content.rich_link_data.assets
object
wajib
Tampilkan atribut turunan
event_payload.data.message.content.rich_link_data.assets.image
object
wajib
Tampilkan atribut turunan
event_payload.data.message.content.rich_link_data.assets.image.source_url
string
wajib
HTTPS URL of a PNG preview image up to 200 kB. Bird fetches and encodes it when sending.
event_payload.data.message.content.rich_link_data.assets.image.mime_type
string
PNG media type required by Apple. Defaults to image/png.
Value: image/png
event_payload.data.message.content.rich_link_data.assets.video
object
Tampilkan atribut turunan
event_payload.data.message.content.rich_link_data.assets.video.url
string
wajib
HTTPS video URL fetched by Apple.
event_payload.data.message.content.rich_link_data.assets.video.mime_type
string
Media type of the video. Defaults to video/mp4; supply the actual type for other formats.
event_payload.data.message.content.rich_link_data_ref
Reusable Apple content reference. Supply the decryption key, or the signed bid and data_ref_sig returned by Apple.
Tampilkan atribut turunan
event_payload.data.message.content.rich_link_data_ref.title
string
Title supplied by Apple for the preview.
event_payload.data.message.content.rich_link_data_ref.url
string
wajib
Location of the encrypted preview.
event_payload.data.message.content.rich_link_data_ref.owner
string
wajib
Owner identifier supplied by Apple.
event_payload.data.message.content.rich_link_data_ref.signature_base64
string
wajib
Signature supplied by Apple.
event_payload.data.message.content.rich_link_data_ref.key
string
wajib
Decryption key supplied by Apple.
event_payload.data.message.content.rich_link_data_ref.size
integer
wajib
Size of the encrypted preview in bytes.
event_payload.data.message.content.interactive_data
A built-in interaction or custom iMessage app. Custom apps require the app metadata and both message bubbles.
Tampilkan atribut turunan
event_payload.data.message.content.interactive_data.session_identifier
string
Session UUID to preserve across interactions. Apple creates one when omitted.
event_payload.data.message.content.interactive_data.data
wajib
Exactly one built-in interaction. Protocol versions are managed by Bird.
Tampilkan atribut turunan
event_payload.data.message.content.interactive_data.data.request_identifier
string
Correlation identifier for this interaction. Bird generates one when omitted.
event_payload.data.message.content.interactive_data.data.images
array of object
Images referenced by identifier.
Tampilkan atribut turunan
event_payload.data.message.content.interactive_data.data.images.identifier
string
wajib
Identifier referenced by a bubble, item, or event.
event_payload.data.message.content.interactive_data.data.images.source_url
string
wajib
HTTPS URL of a PNG image up to 200 kB. Total interactive image data must not exceed 5 MB.
event_payload.data.message.content.interactive_data.data.images.description
string
Accessibility description read by VoiceOver.
event_payload.data.message.content.interactive_data.data.quick_reply
object
wajib
Tampilkan atribut turunan
event_payload.data.message.content.interactive_data.data.quick_reply.summary_text
string
wajib
Text used for the device notification and shown in the transcript after the customer chooses an item. Send a separate text message to introduce the choices.
event_payload.data.message.content.interactive_data.data.quick_reply.items
array of object
wajib
The buttons offered to the customer. Apple requires between two and five; outside that range the request is refused with a 422 AMBQuickReplyItemsInvalid. For more choices, send list_picker content instead.
Tampilkan atribut turunan
event_payload.data.message.content.interactive_data.data.quick_reply.items.identifier
string
wajib
Opaque choice identifier returned in interactive_data.data.quick_reply.selected_identifier.
event_payload.data.message.content.interactive_data.data.quick_reply.items.title
string
wajib
Label shown on the button.
event_payload.data.message.content.interactive_data_ref
Reusable Apple content reference. Supply the decryption key, or the signed bid and data_ref_sig returned by Apple.
Tampilkan atribut turunan
event_payload.data.message.content.interactive_data_ref.title
string
Title supplied by Apple for the preview.
event_payload.data.message.content.interactive_data_ref.url
string
wajib
Location of the encrypted preview.
event_payload.data.message.content.interactive_data_ref.owner
string
wajib
Owner identifier supplied by Apple.
event_payload.data.message.content.interactive_data_ref.signature_base64
string
wajib
Signature supplied by Apple.
event_payload.data.message.content.interactive_data_ref.key
string
wajib
Decryption key supplied by Apple.
event_payload.data.message.content.interactive_data_ref.size
integer
wajib
Size of the encrypted preview in bytes.
event_payload.data.message.in_reply_to_message_id
string
Original message matched through Apple’s request identifier within the same workspace, business, and conversation. Omitted when no verified match exists.
event_payload.data.message.locale
nullable string
Locale for this message, preserved in Apple’s format, for example en_US. Outbound messages use the request override, then the conversation locale, then the business default. Inbound messages preserve the locale in Apple’s callback. Null when unknown.
event_payload.data.message.category
string
The category this message was sent with, for reporting only. It does not affect sending or suppression policy, or select an Apple department or purpose. Defaults to an empty string when a send names no category. Absent on an inbound message, which has no category to report.
event_payload.data.message.metadata
object
Arbitrary JSON object for per-message context. Maximum 2 KB serialized. Top-level keys beginning with __bird are reserved. Returned in the send response, message reads and customer message webhooks.
event_payload.data.message.tags
array of object
Structured {name, value} filter labels applied to this message. Absent on an inbound message.
Tampilkan atribut turunan
event_payload.data.message.tags.name
string
wajib
Tag name. ASCII letters, digits, underscore, and hyphen only. Case-sensitive. Maximum 32 characters.
event_payload.data.message.tags.value
string
wajib
Tag value. ASCII letters, digits, underscore, and hyphen only. Case-sensitive. Maximum 64 characters.
event_payload.data.message.cost
nullable object
wajib
Recorded message charge. Null in the initial send response and while unpriced. The AMB charge is the transaction amount; no passthrough component is priced.
Tampilkan atribut turunan
event_payload.data.message.cost.amount
string
wajib
Total charged, as a decimal string: the sum of the components below. Net of tax, which applies to your wallet balance rather than to an individual charge.
event_payload.data.message.cost.currency_code
string
wajib
ISO 4217 currency code. Every component is denominated in this currency.
event_payload.data.message.cost.transaction_amount
nullable string
wajib
What we charged to carry the message, as a decimal string. null when this component was not priced; "0.00000" when it priced at zero.
event_payload.data.message.cost.passthrough_amount
nullable string
wajib
Third-party fees we pass on, as a decimal string, such as US 10DLC carrier surcharges. null when this component was not priced; "0.00000" when it priced at zero.
event_payload.data.message.last_error
nullable object
Failure detail on a message whose send failed or that Bird rejected before any send attempt. Omitted when there is no failure detail.
Tampilkan atribut turunan
event_payload.data.message.last_error.code
string
wajib
Machine-readable reason a send failed, in one of two namespaces: bird: for a reason Bird's own pipeline assigned (for example bird:business_not_registered), or apple: followed by the HTTP status Apple's API returned for the send attempt (for example apple:404). This is an open, growing set in both namespaces; accept unrecognized values.
event_payload.data.message.last_error.description
string
wajib
The failure in words. Free-form, so branch on code and show this to a human.
event_payload.data.message.last_error.occurred_at
string
wajib
When the failure occurred.
event_payload.data.message.created_at
string
wajib
The moment this message was accepted (outbound) or received (inbound). This is the timestamp the outbound statistics families bucket and attribute on; there is no separate accepted_at field.
event_payload.data.message.sent_at
nullable string
When the selected sending outcome occurred. Null unless the current status is sent and the message is outbound. For older messages without a retained sending event, the stored record time is used.
event_payload.data.message.data_ref
Reusable encrypted content reference returned by Apple after a successful send. Absent until Apple returns one.
Tampilkan atribut turunan
event_payload.data.message.data_ref.title
string
Title supplied by Apple for the preview.
event_payload.data.message.data_ref.url
string
wajib
Location of the encrypted preview.
event_payload.data.message.data_ref.owner
string
wajib
Owner identifier supplied by Apple.
event_payload.data.message.data_ref.signature_base64
string
wajib
Signature supplied by Apple.
event_payload.data.message.data_ref.key
string
wajib
Decryption key supplied by Apple.
event_payload.data.message.data_ref.size
integer
wajib
Size of the encrypted preview in bytes.
event_payload.data.message.group
string
Apple department identifier carried by this message. Omitted when absent from the message or unavailable on a historical record.
event_payload.data.message.intent
string
Apple purpose identifier carried by this message. Omitted when absent from the message or unavailable on a historical record.
error
string
A short explanation of why the event could not be delivered. Present only when your endpoint could not be reached.

Sumber daya terkait

Lanjutkan dengan dokumentasi, panduan, dan contoh untuk topik ini. Sumber daya tersedia dalam bahasa Inggris.

Tonton panduannyaWebhooks done right: reliable delivery eventsPahami konsepnyaHow do I verify a webhook signature?Ikuti jalur pembelajaranOperate messaging reliablyPanduan implementasiWebhooks & events
Coba praktiknya dan dapatkan ringkasan implementasi