Sign inGet Started
Commencer
Guides
Référence API
SDK
CLI
Base de connaissances
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);
Réponse200
{
  "kind": "delivery",
  "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_account_id": "abz_01krdgeqcxet5s7t44vh8rt9mg",
        "direction": "outbound",
        "status": "accepted",
        "kind": "text",
        "source": "operator",
        "text": {
          "body": "Your order has shipped."
        },
        "locale": "en_US",
        "category": "order_update",
        "tags": [
          {
            "name": "category",
            "value": "welcome"
          }
        ],
        "cost": null,
        "created_at": "2026-09-25T11:59:59Z"
      }
    }
  },
  "error": "connection refused",
  "field": "destination.connector.credentials.api_key",
  "client_certificate": "presented"
}

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 and test: true, signed like a real delivery. When the endpoint has a filter, data contains its configured equality values. It does not mirror that event's payload. Tests work on paused endpoints and do not appear in List delivery attempts.

For a connector endpoint, the test checks the endpoint's fields with the connected platform. Where the platform can be read without starting anything, as with Claude Managed Agents, Bird reads it instead of sending an event and returns kind: probe. The status, body and latency are then the platform's answer, and delivered means it accepted the fields, not that an event was delivered. When the platform's answer identifies a wrong field, field names it.

The operation returns 412 if, when event_type is omitted, the endpoint has no subscribed event type to use, or, for a test that sends an event, the endpoint lacks a valid signing secret; a probe needs no signing secret.

Paramètres

webhook_idstring

ID of the webhook endpoint (whk_ prefix), as returned when it was created.

Corps de la requête

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.

Contenu de la réponse

kind
string

What the test did. delivery sent the test event to the endpoint. probe read the connected platform instead, which checks a connector endpoint's fields, sends no event and starts nothing; the status, HTTP details and latency are then the platform's answer to that read. Absent when the test stopped before sending anything, with error saying why.

Possible values: delivery, probe

status
string
obligatoire

Whether the test succeeded. For a delivery, delivered means your endpoint returned a 2xx status to the test event. For a probe, delivered means the platform accepted the endpoint's fields, though no event was sent. failed means a non-2xx status or no answer at all (see error for the latter).

Possible values: delivered, failed

response_status_code
nullable integer
obligatoire

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
obligatoire

Round-trip latency of the request the test sent, in milliseconds; 0 when it sent none.

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.

Afficher les attributs enfants
error
string

A short explanation of a failed test that got no HTTP answer: the endpoint or platform could not be reached, or the test stopped before sending anything, such as for a connector endpoint whose connection no longer exists (then kind is absent).

field
string

For a connector endpoint, the request field that the platform's answer shows is wrong, such as destination.connector.credentials.api_key. Correct it with Update a webhook endpoint. Present only when status is failed and the connector maps that answer to a field.

client_certificate
string

What your endpoint did with the client certificate that we present for your workspace. Omitted when your workspace presents no client certificate, or when the test failed before your endpoint answered.

  • presented: your endpoint asked for the certificate and accepted it.
  • not_requested: your endpoint did not ask for a certificate.
  • rejected: your endpoint rejected the certificate. If your workspace allows deliveries without the certificate, we sent the test again without it, and the other fields show the result of that second request.

Possible values: presented, not_requested, rejected

Ressources associées

Poursuivez avec la documentation, les guides et les exemples sur ce sujet.

Essayez la pratique et obtenez un guide d'implémentation