Help › Keys, CLI and automation
Webhook events reference
On this page
This page lists the events. Delivery, signatures and retries are in Webhooks and the audit log. The full reference with examples is in the repository at docs/events/EVENTS.md.
Every message#
It is JSON with an id, a type, a created time, a siteId (or null for account-level events) and a data object. The id stays the same on retries, so use it to ignore duplicates. Delivery is at least once and not in order.
What is never in a message#
Page text, translation text, addresses of your pages, tokens and keys. Ids, codes, counts and language codes only. Anything that looks like a secret is replaced by [redacted].
Publishing and jobs#
| Event | When | Data |
|---|---|---|
site.published | A publish finished. Nothing is sent when a publish is skipped because nothing changed | version, languages |
job.failed | A scan, translate or publish job will not run again | jobId, kind, code, reason |
quota.reached | A job was stopped because the allowance is used up or a cap applies | reason |
key.rotated | A secret API key was rotated | key id and display prefix, never the key |
site.publish_requested | Someone asked for a publish in the editor | who and which site |
Editing#
translation.edited fires when someone saves a manual translation, marks rows reviewed or reverts rows. It carries the language, counts and the status change, not the text.
Review and team#
review.requested, review.approved, review.rejected, review.withdrawn, comment.added, comment.resolved, invitation.created, invitation.accepted, invitation.revoked, assignment.changed, publish.requested and collab.settings.changed.
Shopify#
shopify.installed and shopify.uninstalled.
Testing#
webhook.ping is sent only when you press "send test event".
Good habits#
- A busy site can raise several
quota.reachedevents in a row. Ignore repeats with the same reason in a short time. job.failedhas a short sentence inreasonthat is safe to show to your staff.- Use
createdandid, not arrival order.
Not every event may be offered to subscribe to in the first release. Which ones can be subscribed to is verify.