Test Webhook delivery | ToAPIs Documentation

POST

/api/v1/webhook/test

Note for users in mainland China: Please use https://api.toapis.cn as the API endpoint (Base URL). Replace https://api.toapis.com with https://api.toapis.cn in the examples in this document.

Behavior

Sends an endpoint.test event to the saved callback URL, for verifying the receiver's signature handling and response. Delivery is asynchronous: HTTP 202 and the returned event_id only mean the event is queued, not delivered. Check the event detail endpoint for the result.

Tests can only use the saved URL — ad-hoc URLs or custom payloads are not supported. mode=off or a global delivery pause returns 409.

Writes reject deleted or scoped keys. Disabled, expired and exhausted model keys can still be managed. Rate limiting is shared with key-lifecycle writes: at most 10 write requests per user per minute. JSON is limited to 16384 bytes with a 10-second body read deadline.

Query parameters, unknown fields and duplicate JSON fields are rejected. Api_key_id must be explicit.

Authentication

Authorizationstringheaderrequired

Use the system access token Bearer YOUR_SYSTEM_ACCESS_TOKEN. Access is limited to your own account. Model keys are not accepted. X-User-Id is not required. There is no administrator or team bypass.

Request parameters

api_key_idintegerbodyrequired

Positive integer ID of your own ordinary model key, not the sk- secret or access token. JSON requires an integer; strings, null, omissions, and query parameters are rejected.

An invalid api_key_id returns 400; a missing or foreign key returns 404; a missing or incomplete configuration or a prohibited test returns 409 (code=16015/16016); rate limiting returns 429.

Request examples

requestExample

curl --request POST \
  --url 'https://api.toapis.com/api/v1/webhook/test' \
  --header 'Authorization: Bearer YOUR_SYSTEM_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{"api_key_id":123}'

Response examples

responseExample

{
  "code": 0,
  "message": "",
  "data": {
    "api_key_id": 123,
    "event_id": "evt_example"
  }
}

For the onboarding order and signature verification, see Get Webhook configuration.