Update Webhook configuration | ToAPIs Documentation

PATCH

/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

Sets or changes a given key's callback URL and enabled state. At least one of enabled and url is required, and omitted fields keep their values. Before enabling you must configure a secret and a public HTTPS callback URL.

enabled=false alone only disables callbacks and keeps the saved URL and secret. url=null clears the callback URL and is only allowed when disabling.

First enablement or a URL change also creates an endpoint.test verification event and returns verification_event_id in the response. A saved configuration does not mean the receiver passed verification.

Disabling only cancels pending events: it does not recall in-flight deliveries, cancel tasks, or issue refunds. Re-enabling does not bring cancelled events back either.

After a URL change, historical events keep the URL recorded when they were created and are not redelivered to the new one.

Writes are not allowed on soft-deleted or scoped keys. Disabled, expired, or exhausted keys can still be managed. Rate limiting is shared with key-lifecycle writes: at most 10 write requests per user per minute.

The request JSON must be a top-level object of at most 16384 bytes with a 10-second body read deadline. Query parameters, unknown fields, and duplicate fields are rejected. api_key_id must be provided explicitly.

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.

enabledbooleanbody

Enable or disable callbacks.

urlstring | nullbody

Public HTTPS callback URL, or null.

Invalid fields or JSON return 400. An invalid URL returns 400 (code=16014). A missing or foreign key returns 404. Enabling with incomplete configuration returns 409 (code=16015). Enablement or URL changes that require verification under mode=off return 409 (code=16016).

Rate limiting returns 429.

Request examples

requestExample

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

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": "2026-11-13T00:00:00Z",
    "mode": "enforce",
    "health": {
      "state": "disabled",
      "failure_kind": null,
      "consecutive_failures": 0,
      "suspended_until": null,
      "last_http_status": null,
      "last_failure_at": null
    },
    "verification_event_id": null
  }
}

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