POST /v1/webhooks — Atom Files Developers

← API referenceChanges & events · API access unavailable

API REFERENCE / WEBHOOKS

`POST` /v1/webhooks

Subscribe a verified HTTPS receiver to events within the caller’s authorized grant. Deliveries are signed and may be repeated, so consumers deduplicate by event ID. A webhook is a prompt to read the change feed, not a replacement for it.

Request fields

Location	Field	Type	Required	Description
Header	`Authorization`	string	Yes	Credential scoped to the authorized resource.
Header	`Content-Type`	string (media type)	Yes	application/json.
Body	`url`	string	Yes	Verified HTTPS receiver.
Body	`event_types`	string[]	Yes	Events within the caller’s grant.

Request example

Example request

POST /v1/webhooks
Authorization: Bearer <scoped token>
Content-Type: application/json

{
  "url": "https://example.app/atom/events",
  "event_types": [
    "file.available",
    "file.version_created",
    "artifact.ready",
    "artifact.purged",
    "processing.failed",
    "processing.cancelled",
    "operation.failed",
    "access.revoked"
  ]
}

HTTP status codes

Status	Meaning
`201 Created`	Success response shown below.
`400 Bad Request`	Invalid receiver URL or event list.
`401 Unauthorized`	Missing, expired, or invalid credential.
`403 Forbidden`	Credential is valid but lacks the required scope or role.
`409 Conflict`	Equivalent webhook registration already exists.
`429 Too Many Requests`	Rate limit reached; honor Retry-After when provided.
`503 Service Unavailable`	Service temporarily unavailable; retry safely.

Response fields

Field	Type	Example
`id`	string	wh_123
`status`	string	pending_verification

Response example

Example response

201 Created
Content-Type: application/json

{
  "id": "wh_123",
  "status": "pending_verification"
}

How it works

Endpoint verification, safe one-time signing-secret delivery, retry window, secret rotation, and list/delete management are required before this design can ship.