Webhooks
Create an endpoint with POST /v1/webhooks. The key needs the webhooks scope. url must be public HTTPS. events is a list of names from the catalog, or ["*"] for every event.
Code
The response includes secret once. Store it. Later reads of the endpoint do not return it. POST /v1/webhooks/{id}/rotate-secret issues a new one and the previous secret stops matching.
PATCH can set status to active or paused. DELETE stops deliveries.
Events
| Event | When it is sent |
|---|---|
video.viewed | Once per playback session, when a viewer starts watching |
video.progress | At each 10% milestone in that session |
video.completed | When a viewer reaches the end |
conversion.fired | When a viewer clicks a call to action. The payload has the button, not a payment amount |
showcase.lead_created | When a viewer submits a showcase lead form for the first time |
video.uploaded | When a video finishes processing and is ready to play |
team.invited | When a workspace invitation is created |
experiment.created | When a draft A/B test is created |
experiment.launched | When an A/B test starts serving traffic |
experiment.promoted | When a variant is promoted to live |
GET /v1/webhooks/events returns this catalog. POST /v1/webhooks/{id}/test delivers one sample event so you can build the receiver first.
Delivery
AtomicPlayer sends POST with a JSON body.
Code
Respond with a 2xx status. A failed delivery is retried after 1 minute, 1 hour, 6 hours, and 12 hours. Store id if you need to ignore a repeat.
Verify the signature
Every delivery includes X-AtomicPlayer-Signature.
Code
t is a Unix timestamp in seconds. v1 is the hex HMAC-SHA256 of ${t}.${rawBody}, signed with the endpoint secret. Use the raw request body, not a re-serialized object. Compare the hex in constant time, and reject a timestamp more than 5 minutes away from now.