Test a Twitter Webhook Delivery API

Send a real HMAC-signed test payload to your webhook and get back the HTTP status your server returned. Verify your integration before live tweets depend on it.

POST/twitter/monitor/webhook/test

Send a real, correctly signed request to one of your webhooks and report back exactly what your server did with it.

This goes through the same delivery path as a live tweet: same signing, same headers, same timeout. If a test succeeds, real deliveries will too.

Headers

Header	Type	Required	Description
`Authorization`	string	Yes	`Bearer YOUR_API_KEY`, the same key used for every other GetXAPI endpoint
`Content-Type`	string	Yes	`application/json`

Request Body

Field	Type	Required	Description
`webhook_id`	string	Yes	UUID of the webhook to test

Notes

Run this before attaching a monitor. It's the cheapest way to catch a broken signature check.
The test payload has type: "test" and no tweet field. If your handler assumes tweet is always present, it will throw here, which is exactly the bug worth finding now.
A delivered: false response is a successful API call. The endpoint tells you what happened; it doesn't fail because your server did.
Test deliveries are not retried.

What your server receives

{
  "type": "test",
  "message": "GetXAPI webhook test",
  "timestamp": "2026-07-26T09:14:22.000Z",
  "delivery_id": "3f1c8a2e-4b7d-4c19-9e5a-8d2f6b1c0a34"
}

With the same headers as a real delivery, including a valid X-GetXAPI-Signature. See the delivery contract for how to verify it.

Response (200)

Your endpoint accepted it:

{ "delivered": true, "http_status": 200, "error": null }

Your endpoint responded, but rejected it:

{ "delivered": false, "http_status": 401, "error": null }

Your endpoint was never reached:

{ "delivered": false, "http_status": 0, "error": "timeout" }

Response Fields

Field	Type	Description
`delivered`	boolean	`true` when your endpoint returned `2xx`
`http_status`	number	Status your server returned, or `0` if it was never reached
`error`	string \| null	Only set when the request failed at the network level: `timeout`, a DNS failure, a refused connection. `null` whenever your server answered at all, including on a `4xx` or `5xx`.

Read the two fields together. http_status: 500, error: null means your server was reached and threw. http_status: 0 with an error string means we never got a response at all: wrong host, firewall, or a handler slower than 10 seconds.

Troubleshooting

What you see	Usual cause
`401` / `403`	Signature check failing. Almost always the body was parsed before verifying. You need the raw bytes.
`404`	Route not registered, or a typo in the URL
`500`	Your handler threw. Common when it assumes `tweet` exists on a `test` payload.
`http_status: 0` with `error: "timeout"`	Server unreachable, or it took longer than 10 seconds to respond

Rate limit

5 requests per minute — the tightest limit in the monitoring API, because each call makes us send a real HTTP request to your server.

A throttled call never contacts your webhook URL. The 429 is returned before we attempt delivery, so a burst of test calls cannot be turned into a burst of traffic against someone else's server.

Limits use a fixed 60-second window and are shared across every API key on your account, so creating extra keys does not raise the ceiling. Every response carries RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset; a 429 adds Retry-After. See rate limits for the full table.

Errors

Status	Meaning
`400`	`webhook_id` missing or not a valid UUID
`403`	Monitoring is not enabled for this account
`404`	No webhook with that ID on your account
`429`	Rate limit exceeded. Wait `retry_after` seconds, then retry

Example

curl -X POST https://api.getxapi.com/twitter/monitor/webhook/test \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "webhook_id": "8f14e45f-ceea-467a-9f2b-1c3d4e5f6a7b" }'

Test Webhook