API
Webhooks: Management API
Create, list, test, and delete webhooks with an API key.
You can manage webhooks with the REST API instead of the dashboard. Use it to register a webhook from a deploy script or to send a test delivery from CI.
Authentication
Send your inference.net API key in the Authorization header:
Authorization: Bearer $INFERENCE_API_KEYWebhooks belong to the team that owns the API key.
- To list or get webhooks, the key needs
readaccess to at least one project in the team. - To create, update, delete, or test webhooks, the key needs
writeaccess to at least one project in the team. The user who created the key must also be a team owner or admin.
Base URL
https://relay.inference.net/api/restThe webhook object
{
"id": "0c6f6a1e-6c1b-4a0e-9a53-2f1f4d0e8b7a",
"name": "Production receiver",
"identifier": "AhALzdz8S",
"teamId": "team_123",
"url": "https://example.com/webhooks/inference",
"isDisabled": false,
"createdAt": "2026-01-03T06:46:22.838Z",
"updatedAt": "2026-01-03T06:46:22.838Z"
}| Field | Description |
|---|---|
id | Webhook ID. Use it in the URL path of the requests below. |
identifier | Webhook identifier. Send it as metadata.webhook_id on generations. Deliveries send it in X-Inference-Webhook-ID. |
name | Name you gave the webhook, or null. |
url | HTTPS URL that receives deliveries. |
isDisabled | true when deliveries are paused. |
Keep the identifier private. Your endpoint uses it to verify that a delivery comes from inference.net.
Create a webhook
POST /webhooks
| Body field | Type | Required | Description |
|---|---|---|---|
url | string | Yes | Public HTTPS URL of your endpoint. |
name | string | No | Name to show in the dashboard. |
curl https://relay.inference.net/api/rest/webhooks \
-H "Authorization: Bearer $INFERENCE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Production receiver",
"url": "https://example.com/webhooks/inference"
}'The response is { "webhook": { ... } }. The URL must use HTTPS and point to a public host. Other URLs fail with 400.
List webhooks
GET /webhooks
| Query parameter | Type | Default | Description |
|---|---|---|---|
limit | integer | 50 | Page size, from 1 to 100. |
offset | integer | 0 | Number of webhooks to skip. |
curl "https://relay.inference.net/api/rest/webhooks?limit=50&offset=0" \
-H "Authorization: Bearer $INFERENCE_API_KEY"The response is { "webhooks": [ ... ], "total": 1 }. total is the number of webhooks in the team.
Get a webhook
GET /webhooks/{webhookId}
curl https://relay.inference.net/api/rest/webhooks/$WEBHOOK_ID \
-H "Authorization: Bearer $INFERENCE_API_KEY"The response is { "webhook": { ... } }.
Update a webhook
PATCH /webhooks/{webhookId}
Send only the fields to change: name, url, or isDisabled.
curl -X PATCH https://relay.inference.net/api/rest/webhooks/$WEBHOOK_ID \
-H "Authorization: Bearer $INFERENCE_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "isDisabled": true }'The response is { "webhook": { ... } }.
Send a test delivery
POST /webhooks/{webhookId}/test
Sends one POST with sample data to the webhook URL, with the same headers as a real delivery. Test ids start with test-.
| Body field | Type | Default | Description |
|---|---|---|---|
eventType | string | webhook.test | Sample event to send: webhook.test, generation.completed, slow-group.completed, or async-embedding.completed. |
curl -X POST https://relay.inference.net/api/rest/webhooks/$WEBHOOK_ID/test \
-H "Authorization: Bearer $INFERENCE_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "eventType": "generation.completed" }'The response tells you how your endpoint answered:
{ "success": true, "statusCode": 200 }success is true only for a 2xx answer within 30 seconds. On failure, error describes the problem and statusCode is the HTTP status your endpoint returned (0 when the request did not complete).
Delete a webhook
DELETE /webhooks/{webhookId}
curl -X DELETE https://relay.inference.net/api/rest/webhooks/$WEBHOOK_ID \
-H "Authorization: Bearer $INFERENCE_API_KEY"The response is { "success": true }. Generations that still name the deleted identifier do not get deliveries. To pause deliveries instead, set isDisabled to true.
Errors
Errors return a JSON body with code and message:
{ "code": "NOT_FOUND", "message": "Webhook not found" }| Status | Code | Cause |
|---|---|---|
400 | BAD_REQUEST | The body or query is not valid, for example a URL that is not public HTTPS. |
401 | UNAUTHORIZED | The API key is missing or not valid. |
403 | FORBIDDEN | The key does not have the required access, or its user is not a team owner or admin. |
404 | NOT_FOUND | No webhook with this ID exists in the team. |
CLI
The inf webhook CLI commands run the same operations, for example inf webhook list and inf webhook test --webhook-id <id>.