API reference

Configure webhook

Create a signed Svix webhook endpoint for an API key. Review Diffio API behavior, response fields, setup details, and production workflows.

Configure a test or live webhook endpoint for an API key using Svix signing.

POST/v1/webhooks/configurePermissions: admin, webhooks:write

Endpoint

HTTP request

https://api.diffio.ai/v1/webhooks/configure

Use POST with a JSON body.

Permissions

admin, webhooks:write

API keys must be active.

Authentication

Send the API key on every request using one of the supported headers.

Authorization: Bearer <apiKey>
X-Api-Key: <apiKey>
Xi-Api-Key: <apiKey>

Request

Provide webhook mode, HTTPS URL, event types, and optionally the target API key id.

Body fields

Field	Type	Required	Description
`mode`	string	Yes	Webhook mode, either test or live.
`url`	string	Yes	HTTPS endpoint URL to receive webhook deliveries.
`eventTypes`	array	Yes	Supported webhook event types to deliver.
`apiKeyId`	string	No	Optional target API key id. Defaults to the authenticated key id.

cURL

curl -X POST "https://api.diffio.ai/v1/webhooks/configure" \  -H "Authorization: Bearer $DIFFIO_AGENT_KEY" \  -H "Content-Type: application/json" \  -d '{    "mode": "live",    "url": "https://example.com/diffio-webhook",    "eventTypes": [      "generation.completed",      "generation.failed"    ],    "apiKeyId": "key_123"  }'

Response

Returns the stored webhook configuration.

Response fields

Field	Type	Required	Description
`webhook`	object	Yes	Stored webhook configuration.
`webhook.apiKeyId`	string	Yes	API key id the endpoint is configured for.
`webhook.mode`	string	Yes	Webhook mode.
`webhook.endpointId`	string	Yes	Svix endpoint id.
`webhook.eventTypes`	array	Yes	Configured event types.
`webhook.url`	string	Yes	Configured HTTPS endpoint URL.
`webhook.signing`	string	Yes	Signing provider, set to svix.
`webhook.updatedByKeyId`	string	Yes	Admin key id that made the change.

Successful response

{  "webhook": {    "apiKeyId": "key_123",    "mode": "live",    "svixEnv": "production",    "appId": "app_123",    "endpointId": "ep_123",    "eventTypes": [      "generation.completed",      "generation.failed"    ],    "url": "https://example.com/diffio-webhook",    "signing": "svix",    "updatedAt": "2026-05-09T12:00:00Z",    "updatedByKeyId": "key_admin_123"  }}

Return codes

200Success, treated as complete.: Webhook endpoint configured.
204Success, treated as empty response.: CORS preflight when method is OPTIONS.
400Bad request, treated as client error.: Invalid JSON body, mode must be test or live, url must be HTTPS, eventTypes must be a non-empty array, or event type is unsupported.
401Unauthorized, treated as auth error.: Missing API key, or invalid API key.
403Forbidden, treated as permission error.: Privileged admin API key required, API key is not active, or missing webhooks:write permission.
404Not found, treated as missing resource.: Target API key not found.
405Client error, treated as fix required.: Method is not POST.
500Server error, treated as retryable.: Failed to initialize webhook app, failed to configure webhook endpoint, missing endpoint id, or failed to store webhook configuration.
503Service unavailable, treated as retryable.: Svix is not configured.

Notes

eventTypes must be generation.queued, generation.processing, generation.failed, or generation.completed.
The endpoint creates a Svix endpoint and stores webhook metadata on the API key document.
The endpoint writes an audit log entry for successful configuration.