Webhook reference
此内容尚不支持你的语言。
What an endpoint of the instance’s webhooks receives: the requests, their signature, the events, and how failures are retried. Setting up a webhook is in the operations guide.
Requests
Section titled “Requests”Each message is one POST to the endpoint’s URL with an application/json body and three headers of
Standard Webhooks:
| Header | Value |
|---|---|
webhook-id |
The message ID, a UUIDv7. It is the same on every attempt and redelivery of the message: use it to drop duplicates. |
webhook-timestamp |
When this attempt was sent, in Unix seconds. |
webhook-signature |
v1, and the base64 of the HMAC-SHA256 of webhook-id.webhook-timestamp.body under the secret. For 24 hours after the secret is rotated, the header carries a signature under the new secret and one under the previous secret, separated by a space. |
The body is:
{ "type": "report.created", "timestamp": "2026-10-20T12:00:00.000Z", "data": { "id": "0192b3c4-...", "category": "spam", "...": "..." }}typeis one of the events below, orwebhook.test.timestampis when the event happened, in RFC 3339 with milliseconds.datais what the admin API (/api/v1/admin/...) answers for the object of the event, as it is when the event happens: the server presents it with the same code as the admin API, in the transaction of the event. The table below names its schema for each type: the admin types are those of the client API reference, and the three types that only webhooks send are under Message data. A field without a value is left out. The OpenAPI document names the bodyWebhookMessage.- v0 keeps no version of the body:
datafollows the admin API of/api/v1, which may change in a v0 minor release.
The secret is whsec_ and the base64 of 32 random bytes, as the Standard Webhooks libraries take it. It is shown once, when the
webhook is set up or its secret rotated. Verify with one of
their libraries, and reject a timestamp far from your
clock to refuse replays.
Events
Section titled “Events”An endpoint subscribes to some of these events. Setting up the subscription needs manage_webhooks and the permission listed.
type |
When | data |
Permission |
|---|---|---|---|
report.created |
A report is filed, locally or by another server (a Flag) |
AdminReport (state open), as GET /admin/reports lists it |
manage_reports |
report.resolved |
A report is resolved | AdminReport (state resolved, with outcome) |
manage_reports |
report.reopened |
A resolved report is reopened | AdminReport (state open) |
manage_reports |
registration.pending |
A registration awaits a moderator’s approval | AdminRegistration (state pending), with the email address and the reason |
manage_accounts |
account.created |
A registration is approved, at the sign-up or by a moderator, and the local account can be used | AdminRegistration (state approved) |
manage_accounts |
account.updated |
A local account changes its profile | AdminAccount, as GET /admin/accounts lists it, with the new profile |
manage_accounts |
moderation_action.created |
An action on an account | AdminAccountAction (state active) |
manage_accounts |
moderation_action.lifted |
The lift of an action on an account | AdminAccountAction (state lifted) |
manage_accounts |
appeal.created |
An account appeals an action | AdminAppeal, with the action |
manage_accounts |
domain_moderation_action.created |
An action on a domain, a moderator’s or a blocklist subscription’s | AdminDomainAction (state active; subscription_id names the subscription that issued it) |
manage_domains |
domain_moderation_action.lifted |
The lift of an action on a domain | AdminDomainAction (state lifted) |
manage_domains |
status.created |
A local account posts publicly | WebhookStatus |
none besides manage_webhooks |
custom_emoji.created |
An administrator registers a custom emoji | WebhookCustomEmoji: AdminCustomEmoji and the operation |
manage_custom_emojis |
custom_emoji.updated |
An administrator replaces the image of a custom emoji, changes its settings or aliases, or enables or disables it | WebhookCustomEmoji (operation says which) |
manage_custom_emojis |
custom_emoji.deleted |
An administrator deletes a custom emoji | WebhookCustomEmoji, the emoji as it was before the deletion |
manage_custom_emojis |
error_group.created |
The server or the web client reports an error of a new kind | ErrorGroup, as GET /admin/error_groups lists it |
manage_errors |
error_group.regressed |
An error group that an administrator resolved happens again on another version of the server | ErrorGroup (state open) |
manage_errors |
webhook.test |
An administrator sends a test message to the endpoint | WebhookTest |
— (not subscribable) |
status.createdis sent forpublicposts only:unlisted,local,private, anddirectposts never leave the server this way, and neither do remote posts. A reply that waits for the approval of the author of the post it replies to is sent when it is approved, not before.account.updatedis sent for local accounts only, and not for the profile an account is created with.custom_emoji.*follows the administrators’ operations only, never the remote emoji that posts and profiles bring.error_group.*never follows a web client report sent without a session: a group that only such reports have seen is sent aserror_group.createdwhen the first report from a signed-in user arrives, unless it is muted by then, and a recurrence reported without a session is not sent. Itsdatais presented when the group is recorded, before the occurrence is counted, socount_24handcount_7dmay be0, and it has nodaily_counts, which only the list of the admin API carries. A recurrence on the same version of the server is only counted.- The
dataof the admin types embeds what the admin API embeds: the reporter’s and the target’sAccountinAdminReport, the account’sAccountinAdminAccount, the action inAdminAppeal, the image URLs inAdminCustomEmoji. A registration carries the applicant’s email address, and a report the reporter’s comment: the messages are kept 14 days (below). - The permissions are checked when a webhook is set up or changed. A webhook keeps its events when the person who set it up later
loses a permission; someone with
manage_webhooksdisables it when it should stop.
Message data
Section titled “Message data”No admin operation answers the data of status.created, custom_emoji.*, and webhook.test, so their fields are here.
WebhookStatus, the post of status.created:
| Field | Type | Value |
|---|---|---|
id |
string | The ID of the post. |
uri |
string | The ActivityPub id of the post. |
account_id |
string | The ID of the local account that posted it. |
visibility |
string | Always public. |
in_reply_to_uri |
string | The ActivityPub id of the post it replies to; left out when it is not a reply. |
spoiler_text |
string | The content warning, or an empty string. |
sensitive |
boolean | Whether the media of the post is marked sensitive. |
language |
string | The language of the post. |
content |
string | The sanitized HTML of the post in its language. |
created_at |
string | When the post was published, in RFC 3339 with milliseconds. |
WebhookCustomEmoji, the emoji of custom_emoji.*, is AdminCustomEmoji of the
client API reference with one more field:
| Field | Type | Value |
|---|---|---|
operation |
string | What the administrator did, named as in the audit log: custom_emoji_created, custom_emoji_image_replaced, custom_emoji_copied, custom_emoji_updated, custom_emoji_enabled, custom_emoji_disabled, or custom_emoji_deleted. |
WebhookTest, the data of webhook.test:
| Field | Type | Value |
|---|---|---|
endpoint_id |
string | The ID of the webhook the test message was sent to. |
Answers, retries, and disabling
Section titled “Answers, retries, and disabling”- A
2xxanswer delivers the message. The body of the answer is not read. 410 Gonedisables the webhook at once.- Any other answer, redirects included (they are never followed), no answer within 15 seconds, and a failed connection fail the
attempt. An answer with a status code outside 100-599 is not valid HTTP, and is recorded with the outcome
connection_errorand no status code. A failed attempt is retried after 5 seconds, 5 minutes, 30 minutes, 2 hours, 5 hours, 10 hours, and 10 hours: 8 attempts over about 27 hours. ARetry-Afterheader (seconds or an HTTP date, up to 1 hour) replaces the next wait. After the last attempt the delivery stops; an administrator can send it again from the administration screen, with the samewebhook-id. - When the attempts to a webhook fail without a success for 72 hours and at least 20 times in a row, the server disables it,
records it in the audit log as the system, and notifies the users with
manage_webhooks. - A disabled webhook receives nothing, also of the deliveries waiting to be retried, and enabling it again does not send the messages of the time it was disabled.
- The messages and their deliveries are kept for 14 days and then deleted.
Destinations
Section titled “Destinations”The server sends through its SSRF guard, the same one as federation: the URL must be https (or http) on a public address. A destination on
loopback or a private network, such as an automation tool on the same host or in the same VPC, is reached only when the operator
lists it in webhook_allowed_destinations (configuration reference); such a
destination may also use plain http and any port. An attempt to a destination the guard refuses fails with the outcome
forbidden_destination.
The audit log and the logs show the host name of a URL and never the URL itself: chat services put a secret in the path or the query of their webhook URLs.
供 LLM 和编程智能体使用:llms.txt,llms-full.txt, llms-small.txt