Ir al contenido

Webhook reference

Esta página aún no está disponible en tu idioma.

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.

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", "...": "..." }
}
  • type is one of the events below, or webhook.test.
  • timestamp is when the event happened, in RFC 3339 with milliseconds.
  • data is 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 body WebhookMessage.
  • v0 keeps no version of the body: data follows 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.

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.created is sent for public posts only: unlisted, local, private, and direct posts 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.updated is 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 as error_group.created when 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. Its data is presented when the group is recorded, before the occurrence is counted, so count_24h and count_7d may be 0, and it has no daily_counts, which only the list of the admin API carries. A recurrence on the same version of the server is only counted.
  • The data of the admin types embeds what the admin API embeds: the reporter’s and the target’s Account in AdminReport, the account’s Account in AdminAccount, the action in AdminAppeal, the image URLs in AdminCustomEmoji. 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_webhooks disables it when it should stop.

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.
  • A 2xx answer delivers the message. The body of the answer is not read.
  • 410 Gone disables 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_error and 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. A Retry-After header (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 same webhook-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.

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.

Para LLM y agentes de programación:llms.txt,llms-full.txt, llms-small.txt

Analítica de este sitio