test_webhook_endpoint

Queue a synthetic test event to an endpoint so its consumer can be checked end to end. Returns the queued delivery to poll.

Purpose

Send an endpoint a signed test event without waiting for something real to happen. The answer is the queued delivery in the get_webhook_delivery row shape, status pending; poll that tool for the target's response_status and response_excerpt once the worker has posted it.

Same worker, same signature, same ladder

The test delivery is posted by the same job that posts real events, signed with the endpoint's current secret, and retried on the same ladder if the target fails. A consumer that verifies the signature and returns 2xx for the test will do so for real events.

Only the creator who registered the endpoint, or the team owner, may fire a test; a fellow team member is refused with FORBIDDEN. REST rate-limits the same action to five per minute per endpoint.

Required ability

webhook-endpoint:update

Input schema

{
  "type": "object",
  "required": ["endpoint_id"],
  "properties": {
    "endpoint_id": {
      "type": "string",
      "description": "UUID of the webhook endpoint to send a test event to."
    }
  }
}

Output shape

{
  "data": {
    "id": "34f1d78e-05a2-4b69-8c3d-7e921ab06f45",
    "endpoint_id": "c62a08f4-1b7d-4e35-9860-a37f5d21e0b9",
    "event": "webhook.test",
    "event_id": "01HXZ3Q8M7Y2K4N6P9R1T3V5W7",
    "status": "pending",
    "attempts": 0,
    "response_status": null,
    "response_excerpt": null,
    "payload": {
      "id": "evt_01HXZ3Q8M7Y2K4N6P9R1T3V5W7",
      "type": "webhook.test",
      "created_at": "2026-09-06T09:20:00+00:00",
      "api_version": "2026-05-01",
      "project_id": null,
      "data": {}
    },
    "next_attempt_at": null,
    "delivered_at": null,
    "dead_lettered_at": null,
    "created_at": "2026-09-06T09:20:00+00:00"
  }
}

Example prompts

"Send a test event to webhook endpoint c62a08f4-1b7d-4e35-9860-a37f5d21e0b9 and tell me what it answered."

"We just deployed the handler — fire a test at the CRM sync endpoint."

"Check the finance webhook is still accepting deliveries."

Failure modes

FORBIDDEN — the token belongs to a team member who did not register the endpoint and is not the team owner.
VALIDATION_FAILED — the test was refused for the endpoint's current state.
RESOURCE_NOT_FOUND — unknown endpoint_id, or an endpoint of another team.
AUTHENTICATION_REQUIRED — no authenticated user on the request.
TOKEN_MISSING_ABILITY — token lacks webhook-endpoint:update.

get_webhook_delivery — poll the returned id for the result.
list_webhook_deliveries — the whole log.
Webhook endpoints API — the REST equivalent.
Testing and debugging webhooks