Test Webhook API

POST webhook/{id}/test sends one real HMAC-signed test event to the webhook's configured URL immediately and returns the delivery outcome in the same response: whether it was delivered (2xx received within the timeout), the HTTP status code your endpoint returned, and an error message if delivery failed.

curl -X POST "https://example.com/webhook/{id}/test"

{  "id": "e4a1f9c2-3b7d-4a88-9f1e-2c6d8b4a5e10",  "delivered": true,  "status_code": 200,  "error": null}

{  "error": "bad_request",  "message": "Missing or malformed parameter. Fix the request before retrying."}

{  "error": "unauthorized",  "message": "The API key is missing, malformed, or revoked. Check the Authorization header."}

{  "error": "insufficient_credits",  "message": "Your balance is exhausted. Top up your credits to continue."}

{  "error": "forbidden",  "message": "The acting account is not authorized for this write action, or has no logged-in session."}

{  "error": "not_found",  "message": "The resource does not exist, for example a deleted tweet or a private account."}

{  "error": "rate_limited",  "message": "Too many requests. Back off and retry with exponential backoff."}

{  "error": "server_error",  "message": "Something failed on our side. Retry with backoff; if it persists, contact support."}

Pricing

When to use

Use this endpoint right after creating or editing a webhook, when you need to confirm your endpoint is reachable and correctly verifying the HMAC signature before relying on real monitor events. Unlike the other Monitoring endpoints, which read or manage ongoing event delivery, this one triggers a single synchronous send-and-report cycle on demand.

Notes

• Replace {id} with the webhook's id.
• Returns HTTP 200 when delivered is true, HTTP 502 when it is false (your endpoint failed, not ours).
• Works even on a webhook a 410 Gone response has disabled, so you can verify a fix before there is a separate re-enable action.
• The test payload's event field is "webhook.test", not "tweet.created", so your handler can distinguish a real event from a test send if it needs to.

Related endpoints

• Create Monitor: Watch an X account for new posts and push them to your webhook(s).
• List Monitors: List every monitor on your account.

FAQ

Does a failed test retry or get dead-lettered like a real event?

No. The description states a test send is never queued, retried, or dead-lettered. If delivered is false, you get one error explanation in the response and must trigger another test call yourself to try again.

What does status_code contain if my endpoint never responds?

status_code is null if the request failed before a response was received, for example a connection timeout or DNS failure. In that case delivered is false and the error field explains why, while status_code carries no HTTP status because none was returned.