Events
Webhook event names, the delivery envelope, and signature verification.
Register an endpoint under Webhooks
and Videohati sends an HTTP POST to it each time one of the MVP events fires.
You receive these deliveries — you never call the delivery endpoint yourself.
For the end-to-end setup — registering an endpoint, verifying signatures, and
handling retries in your own server — see the webhooks guide.
Event names
| Event | Fires when |
|---|---|
video.upload.completed | A multipart upload finished and the source object landed in storage. |
video.encoding.ready | Encoding finished; the video can be played. |
video.encoding.failed | Encoding failed for the video. |
video.deleted | A video was soft-deleted. |
playback.started | A playback session began playing. |
playback.completed | A playback session reached the end of the video. |
payment.succeeded | A payment for the account succeeded. |
payment.failed | A payment for the account failed. |
Envelope
Every delivery body is a JSON object with this shape:
{
"id": "01JZ9WV3N8GQ5T2M7K4C6XBARM",
"type": "video.encoding.ready",
"created_at": "2026-06-11T11:00:00.000Z",
"project_id": "01JZ9WV3N8GQ5T2M7K4C6XBARF",
"data": {
"videoId": "01JZ9WV3N8GQ5T2M7K4C6XBARH"
}
}id— ULID of this event. Use it to deduplicate retries.type— one of the event names above.created_at— ISO-8601 timestamp.project_id— the project the event belongs to.data— event-specific payload.
Signature verification
Each delivery carries the header:
Videohati-Signature: t=<unix_ts>,v1=<hex_sha256>The HMAC-SHA256 covers the string <unix_ts>.<raw_body> using the endpoint's
signing secret (returned once at registration or rotation). To verify:
- Read
tandv1from the header. - Reject if
tis too old (a 5-minute tolerance keeps replays out). - Compute
HMAC_SHA256(secret, t + "." + rawBody)as lowercase hex. - Compare against
v1with a constant-time comparison.
The official SDKs ship a webhooks.verify helper that does all four steps. Always
verify against the raw request body — not a re-serialized object.
Acknowledging a delivery
Return any 2xx within 10 seconds to acknowledge. Non-2xx responses (or
timeouts) are retried on the delivery schedule.