Get Webhook configuration | ToAPIs Documentation

GET

/api/v1/webhook

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

Reads a given key's webhook configuration, including the callback URL, enabled state, and recent delivery health. Each model key has one webhook configuration, and soft-deleted keys can still be read.

The endpoint only returns secret_configured to indicate whether a secret is set, never the secret itself. Unset URL and timestamps return null. Management API times use RFC 3339.

When health lookup fails health.state=unknown, which does not mean the configuration write failed.

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_idintegerqueryrequired

Positive integer ID of your own ordinary model key, not the sk- secret or access token. The query parameter must be a positive integer; omissions and null are rejected.

A missing or non-positive api_key_id returns 400; a missing or foreign key returns 404; rate limiting returns 429. mode=off only restricts writes and does not affect this read.

Request examples

requestExample

curl --request GET \
  --url 'https://api.toapis.com/api/v1/webhook?api_key_id=123' \
  --header 'Authorization: Bearer YOUR_SYSTEM_ACCESS_TOKEN'

Response examples

responseExample

{
  "code": 0,
  "message": "",
  "data": {
    "api_key_id": 123,
    "enabled": false,
    "url": null,
    "secret_configured": false,
    "previous_secret_expires_at": null,
    "updated_at": null,
    "mode": "enforce",
    "health": {
      "state": "disabled",
      "failure_kind": null,
      "consecutive_failures": 0,
      "suspended_until": null,
      "last_http_status": null,
      "last_failure_at": null
    }
  }
}

First-time setup

Call POST /api/v1/webhook/rotate-secret to generate the signing secret. secret is returned only once in that response; save it on the receiving side immediately. Initialization does not enable callbacks.
Configure signature verification on the receiver as described below.
Call PATCH /api/v1/webhook with your callback URL and enabled=true. First enablement or a URL change creates an endpoint.test verification event and returns verification_event_id.
Call POST /api/v1/webhook/test to send a test event, or query GET /api/v1/webhook/events/{event_id} to inspect verification and delivery results.

Signature verification

Every callback request carries three headers: X-ToAPIs-Webhook-Id (the event ID), X-ToAPIs-Webhook-Timestamp (a Unix-second timestamp), and X-ToAPIs-Webhook-Signature (the signature).

To verify, join the event ID, timestamp, and raw request body with . into event_id.timestamp.raw_body, compute HMAC-SHA256 with the saved secret, and compare it with the hex digest after v1= in the signature header. Verify against the raw body bytes.

Do not parse and re-serialize the JSON. During secret rotation the signature header may contain several comma-separated v1= values, and any match is valid. Deduplicate deliveries by event ID.

Callback payloads and signature timestamps use Unix seconds, while management-endpoint times use RFC 3339.