Skip to main content
Create and manage webhook subscriptions to receive real-time notifications when events occur in your Avala organization.
Webhooks deliver event payloads to your HTTPS endpoint via POST requests. Each delivery is signed with your webhook secret so you can verify authenticity. Failed deliveries are retried automatically.

​
List Webhooks

GET /api/v1/webhooks/
Returns all webhook subscriptions for the authenticated user’s organization, ordered by most recent first.

​
Parameters

NameTypeRequiredDescription
cursorstringNoCursor for pagination (query parameter)
limitintegerNoNumber of results per page (query parameter)

​
Request

curl "https://api.avala.ai/api/v1/webhooks/" \
  -H "X-Avala-Api-Key: $AVALA_API_KEY"

​
Response

{
  "next": null,
  "previous": null,
  "results": [
    {
      "uid": "c2d3e4f5-a6b7-8c9d-0e1f-2a3b4c5d6e7f",
      "target_url": "https://my-app.example.com/avala-webhook",
      "events": ["result.submitted", "export.completed"],
      "is_active": true,
      "created_at": "2025-02-10T08:00:00Z",
      "updated_at": "2025-02-10T08:00:00Z"
    }
  ]
}

​
Fields

FieldTypeDescription
uidstring (UUID)Unique identifier for the webhook subscription
target_urlstringHTTPS URL where event payloads are delivered
eventsarrayList of event types this webhook subscribes to
is_activebooleanWhether the webhook is currently enabled
created_atstring (datetime)ISO 8601 timestamp of when the webhook was created
updated_atstring (datetime)ISO 8601 timestamp of the last update

​
Create Webhook

POST /api/v1/webhooks/
Creates a new webhook subscription. If no secret is provided, one is generated automatically. The secret field is returned only in the creation response. Store it securely — it is used to verify delivery signatures and cannot be retrieved later.

​
Parameters

NameTypeRequiredDescription
target_urlstringYesHTTPS URL to receive webhook payloads
eventsarrayYesEvent types to subscribe to (see Event Types)
secretstringNoSigning secret (auto-generated if not provided, write-only)
is_activebooleanNoWhether the webhook is enabled (default: true)

​
Request

curl -X POST "https://api.avala.ai/api/v1/webhooks/" \
  -H "X-Avala-Api-Key: $AVALA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "target_url": "https://my-app.example.com/avala-webhook",
    "events": ["result.submitted", "export.completed"]
  }'

​
Response

{
  "uid": "c2d3e4f5-a6b7-8c9d-0e1f-2a3b4c5d6e7f",
  "target_url": "https://my-app.example.com/avala-webhook",
  "secret": "e8b2c4a6d0f1e3b5a7c9d1f3e5b7a9c1d3f5e7b9a1c3d5f7e9b1a3c5d7f9e1b3",
  "events": ["result.submitted", "export.completed"],
  "is_active": true,
  "created_at": "2025-02-10T08:00:00Z",
  "updated_at": "2025-02-10T08:00:00Z"
}
The secret is only returned once, at creation time. Store it securely. Use it to verify the X-Avala-Signature header on incoming deliveries.

​
Get Webhook

GET /api/v1/webhooks/{uid}/
Returns the details of a specific webhook subscription.

​
Parameters

NameTypeRequiredDescription
uidstring (UUID)YesWebhook subscription UID (path parameter)

​
Request

curl "https://api.avala.ai/api/v1/webhooks/c2d3e4f5-a6b7-8c9d-0e1f-2a3b4c5d6e7f/" \
  -H "X-Avala-Api-Key: $AVALA_API_KEY"

​
Response

{
  "uid": "c2d3e4f5-a6b7-8c9d-0e1f-2a3b4c5d6e7f",
  "target_url": "https://my-app.example.com/avala-webhook",
  "events": ["result.submitted", "export.completed"],
  "is_active": true,
  "created_at": "2025-02-10T08:00:00Z",
  "updated_at": "2025-02-10T08:00:00Z"
}

​
Fields

Same as List Webhooks fields.

​
Update Webhook

PUT /api/v1/webhooks/{uid}/
Updates an existing webhook subscription. You can also use PATCH for partial updates. The secret cannot be changed through this endpoint.

​
Parameters

NameTypeRequiredDescription
uidstring (UUID)YesWebhook subscription UID (path parameter)
target_urlstringYes (PUT)HTTPS URL to receive webhook payloads
eventsarrayYes (PUT)Event types to subscribe to
is_activebooleanNoWhether the webhook is enabled

​
Request

curl -X PATCH "https://api.avala.ai/api/v1/webhooks/c2d3e4f5-a6b7-8c9d-0e1f-2a3b4c5d6e7f/" \
  -H "X-Avala-Api-Key: $AVALA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "events": ["result.submitted", "result.accepted", "result.rejected"]
  }'

​
Response

{
  "uid": "c2d3e4f5-a6b7-8c9d-0e1f-2a3b4c5d6e7f",
  "target_url": "https://my-app.example.com/avala-webhook",
  "events": ["result.submitted", "result.accepted", "result.rejected"],
  "is_active": true,
  "created_at": "2025-02-10T08:00:00Z",
  "updated_at": "2025-02-10T12:00:00Z"
}

​
Delete Webhook

DELETE /api/v1/webhooks/{uid}/
Permanently deletes a webhook subscription. Pending deliveries for this webhook will not be retried.

​
Parameters

NameTypeRequiredDescription
uidstring (UUID)YesWebhook subscription UID (path parameter)

​
Request

curl -X DELETE "https://api.avala.ai/api/v1/webhooks/c2d3e4f5-a6b7-8c9d-0e1f-2a3b4c5d6e7f/" \
  -H "X-Avala-Api-Key: $AVALA_API_KEY"

​
Response

Returns 204 No Content on success.

​
Test Webhook

POST /api/v1/webhooks/{uid}/test/
Sends a test ping event to the webhook’s target URL. The delivery is processed asynchronously — check the List Deliveries endpoint to see the result.

​
Parameters

NameTypeRequiredDescription
uidstring (UUID)YesWebhook subscription UID (path parameter)

​
Request

curl -X POST "https://api.avala.ai/api/v1/webhooks/c2d3e4f5-a6b7-8c9d-0e1f-2a3b4c5d6e7f/test/" \
  -H "X-Avala-Api-Key: $AVALA_API_KEY"

​
Response

{
  "detail": "Test webhook queued.",
  "delivery_uid": "f6a7b8c9-d0e1-2f3a-4b5c-6d7e8f9a0b1c"
}

​
List Deliveries

GET /api/v1/webhook-deliveries/
Returns all webhook delivery attempts for the authenticated user’s organization, ordered by most recent first.

​
Parameters

NameTypeRequiredDescription
cursorstringNoCursor for pagination (query parameter)
limitintegerNoNumber of results per page (query parameter)

​
Request

curl "https://api.avala.ai/api/v1/webhook-deliveries/" \
  -H "X-Avala-Api-Key: $AVALA_API_KEY"

​
Response

{
  "next": null,
  "previous": null,
  "results": [
    {
      "uid": "f6a7b8c9-d0e1-2f3a-4b5c-6d7e8f9a0b1c",
      "subscription": "c2d3e4f5-a6b7-8c9d-0e1f-2a3b4c5d6e7f",
      "event_type": "result.submitted",
      "payload": {
        "event": "result.submitted",
        "result_uid": "990c1800-b62f-85a8-e150-880099881111"
      },
      "response_status": 200,
      "response_body": "{\"ok\": true}",
      "attempts": 1,
      "next_retry_at": null,
      "status": "delivered",
      "created_at": "2025-02-10T14:00:00Z",
      "updated_at": "2025-02-10T14:00:01Z"
    }
  ]
}

​
Delivery Fields

FieldTypeDescription
uidstring (UUID)Unique identifier for the delivery
subscriptionstring (UUID)UID of the webhook subscription
event_typestringEvent type that triggered this delivery
payloadobjectEvent payload that was sent
response_statusinteger | nullHTTP status code from the target URL
response_bodystring | nullResponse body from the target URL
attemptsintegerNumber of delivery attempts made
next_retry_atstring (datetime) | nullWhen the next retry is scheduled, if applicable
statusstringDelivery status (see Delivery Statuses)
created_atstring (datetime)ISO 8601 timestamp of creation
updated_atstring (datetime)ISO 8601 timestamp of the last update

​
Get Delivery

GET /api/v1/webhook-deliveries/{uid}/
Returns the details of a specific webhook delivery.

​
Parameters

NameTypeRequiredDescription
uidstring (UUID)YesDelivery UID (path parameter)

​
Request

curl "https://api.avala.ai/api/v1/webhook-deliveries/f6a7b8c9-d0e1-2f3a-4b5c-6d7e8f9a0b1c/" \
  -H "X-Avala-Api-Key: $AVALA_API_KEY"

​
Response

Same format as individual items in List Deliveries.

​
Event Types

EventDescription
dataset.createdA new dataset was created
dataset.updatedAn existing dataset was updated
dataset.deletedA dataset was deleted
export.completedAn export job completed successfully
export.failedAn export job failed
task.completedA task was marked as complete
result.submittedAn annotation result was submitted
result.acceptedAn annotation result was accepted
result.rejectedAn annotation result was rejected
auto_label.completedAn auto-label job finished successfully
auto_label.failedAn auto-label job failed
quality.alertA quality target threshold was breached

​
Delivery Statuses

StatusDescription
pendingDelivery is queued and has not been attempted yet
deliveredPayload was successfully delivered (received 2xx response)
failedAll delivery attempts failed

​
Error Responses

​
Validation Error (400)

{
  "events": ["Invalid events: invalid.event"],
  "target_url": ["A webhook subscription for this URL already exists."]
}
Returned when the request body contains invalid events or a duplicate target URL.

​
Unauthorized (401)

{
  "detail": "Invalid API key."
}
Returned when the X-Avala-Api-Key header is missing or contains an invalid key.

​
Permission Denied (403)

{
  "detail": "You do not have permission to perform this action."
}
Returned when the authenticated user does not have access to the requested webhook.

​
Not Found (404)

{
  "detail": "Not found."
}
Returned when the specified webhook or delivery UID does not exist.