Event Webhooks
Subscribe to real-time project events such as uploads, session state changes, and billing notifications.
Available Topics
Subscribe to specific event topics or use wildcards to match multiple events.
| Topic | Description |
|---|---|
| project.upload.started | An image upload has started processing |
| project.upload.completed | An image upload has been delivered to all destinations |
| project.upload.failed | An image delivery failed after all retries |
| project.session.created | A new upload session was created |
| project.session.expired | An upload session has expired |
| project.billing.plan_changed | The project billing plan was changed |
Use wildcards like project.upload.* to match all events in a category.
Create a Webhook
POST
/api/v1/projects/:projectId/webhooksRegister a new event webhook endpoint for a project.
curl -X POST https://api.apertur.ca/api/v1/projects/proj_.../webhooks \
-H "Authorization: Bearer aptr_live_xxxx" \
-H "Content-Type: application/json" \
-d '{
"url": "https://api.example.com/events",
"topics": ["project.upload.*", "project.billing.plan_changed"]
}'Delivery History
Inspect delivery attempts for a webhook and retry failed deliveries.
# List delivery attempts curl https://api.apertur.ca/api/v1/projects/proj_.../webhooks/wh_.../deliveries \ -H "Authorization: Bearer aptr_live_xxxx" # Retry a failed delivery curl -X POST https://api.apertur.ca/api/v1/projects/proj_.../webhooks/wh_.../deliveries/del_.../retry \ -H "Authorization: Bearer aptr_live_xxxx"
Verifying Signatures
Event webhooks are signed using HMAC SHA-256 or Svix. Verify the X-Apertur-Signature header to ensure authenticity.
# Event webhooks are received at your endpoint.
# Verify the signature using the X-Apertur-Timestamp and X-Apertur-Signature headers.
#
# Payload:
# {
# "event": "project.upload.completed",
# "project_id": "proj_...",
# "data": { ... },
# "timestamp": "2025-01-15T12:00:00Z"
# }Payload Format
All event webhooks share a common envelope format with the event type, project ID, event data, and a timestamp.
{
"event": "project.upload.completed",
"project_id": "proj_...",
"data": {
"session_id": "sess_01HX...",
"image_id": "img_01HX...",
"filename": "photo.jpg",
"size_bytes": 245000
},
"timestamp": "2025-01-15T12:00:00Z"
}