Send a test event to a webhook endpoint
POST /v1/webhook-endpoints/{endpoint_id}:test · permission webhook-endpoints:write · all plans
Sends one signed synthetic event of the chosen type (default user.created) to the endpoint and returns the outcome. The event carries data.test = true and is signed with the endpoint's current secret, exactly like a real delivery, so you can check your signature verification. No delivery record is written and the receiver's response body is not returned. Each endpoint allows 10 tests per minute.
Request
| Field | Type | Required | Description |
|---|---|---|---|
endpoint_id |
path | yes | Webhook endpoint ID (whe_…). |
event_type |
string | no | Event catalog type to send; default user.created. The body is optional. |
Idempotency-Key |
header | no | Replays the result for a repeated request with the same key. |
{
"event_type": "user.updated"
}
Response
200 OK with the outcome. A failed delivery is still 200: succeeded is false and error_class says why (timeout, tls, dns, egress_blocked, http_status, connection).
{
"succeeded": true,
"http_status": 204,
"error_class": null,
"latency_ms": 87,
"event_id": "evt_01k8a3m7s9v1w3x5y7z9b2c4d6"
}
Errors
| HTTP | code | When |
|---|---|---|
| 400 | unknown_field |
The body has a field that is not listed above. |
| 404 | not_found |
No such endpoint in this environment. |
| 409 | conflict |
The endpoint is not enabled. |
| 422 | validation_failed |
/event_type unknown_event_type: not a catalog type. |
| 429 | rate_limited |
More than 10 tests a minute for this endpoint; retry after Retry-After. |
| 401 | unauthenticated |
The credential is missing, invalid or revoked. |
| 403 | insufficient_permissions |
The credential lacks webhook-endpoints:write. |
| 503 | service_unavailable |
Webhook administration is temporarily unavailable; retry after the Retry-After period. |
Example
curl -X POST https://api.eu.keenauth.com/v1/webhook-endpoints/whe_01k8a3m5q7t9v1w3x5y7z9b2c4:test \
-H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{"event_type":"user.updated"}'
CLI: keenauth webhook-endpoints test whe_01k8a3m5q7t9v1w3x5y7z9b2c4 --event-type user.updated