Events
An app subscribes a URL to events in Apps and integrations. The URL must first
answer a url_verification request — {"type": "url_verification", "token": "", "challenge": "…"} — by echoing the challenge, either as the whole body or as
{"challenge": "…"}.
Each event then arrives as:
{
"type": "event_callback",
"event_id": "Ev1234",
"event_time": 1789291228,
"team_id": "01M2D12P7QFB85N50CZ4MHTV46",
"event": { "type": "message", "channel": "…", "user": "…", "text": "…", "ts": "…" },
"ownbase": { "type": "message.created", "seq": 1234 }
}
ownbase carries this server's own event name and its position in the
workspace's event log. There is no api_app_id, authorizations,
event_context or verification token.
What is delivered:
- events from channels the bot has been added to, and workspace-wide events such as a new member;
- never an event caused by the app's own bot, which is how a bot that answers messages ends up answering itself forever;
- only the event types the subscription names, using the native names in the table below, or every type if it names none. A subscription naming any other type is refused;
- only what the app's scopes let it read, as the table's last column says. A
message from a private channel needs
groups:historywhere one from a public channel needschannels:history. Apps and integrations names the scopes a subscription's events are waiting on. Events already queued when a scope is taken away are still sent.
How it is delivered:
- at least once. A crash after the app answered but before the delivery was
recorded sends it again with the same
event_id, so deduplicate on it; - in order for each subscription, and in parallel across subscriptions;
- a
2xxanswer within four seconds is a delivery. Anything else is retried after 5 seconds, 30 seconds, 2 minutes, 10 minutes, 30 minutes, 1 hour and 6 hours — eight attempts in all — withX-Slack-Retry-NumandX-Slack-Retry-Reason: http_erroron each retry; - at most 500 events wait for one subscription. Past that, new events are counted as dropped and shown beside the subscription;
- an endpoint that uses up its attempts has the rest of its queue given up with it. An administrator can retry the whole queue, in order, from Apps and integrations. Given-up events nobody asks to retry are kept for seven days; a retry that has been asked for is kept until it is sent, however long the queue stays full, or until the endpoint fails again, which starts its seven days afresh;
- a retry is a replay of history. Its events go out oldest first among
themselves, each taking a place in the queue as one frees up, but events
already waiting when the retry was asked for are not held back for it. So a
replayed event can arrive after newer ones: order by
ownbase.seq(orevent_id) if your app needs the original order.
What an edit or a deletion does to an event not yet delivered: a message's
words are taken out of every event about it that is still waiting, or that
gave up, in the same write that edits or deletes it, and the same happens when
the retention window discards it. The events themselves stay, in order and with
their event_id: an app that is behind receives the message with an empty
text (or a message_changed whose message.text is empty), then the edit or
deletion that supersedes it, as a client catching up on the event log does.
Only the words are taken out; who wrote it, where and when stay. An event
already delivered belongs to the app and cannot be called back, and one that was
on its way out at that moment may still arrive as it was.
The events — checked:
| Native event | Slack event.type | Differences | Scope |
|---|---|---|---|
message.created | message | thread_ts present for a reply | channels:history, groups:history, im:history, mpim:history |
message.updated | message | subtype: "message_changed", with the new message | channels:history, groups:history, im:history, mpim:history |
message.deleted | message | subtype: "message_deleted", with deleted_ts | channels:history, groups:history, im:history, mpim:history |
reaction.added | reaction_added | reaction is the emoji itself, not its name | reactions:read |
reaction.removed | reaction_removed | As above | reactions:read |
pin.added | pin_added | — | pins:read |
pin.removed | pin_removed | No user | pins:read |
channel.created | channel_created | — | channels:read, groups:read |
channel.updated | channel_rename | Sent for any change to a channel, not only its name | channels:read, groups:read |
member.joined | member_joined_channel | — | channels:read, groups:read |
member.left | member_left_channel | — | channels:read, groups:read |
user.joined | team_join | user carries id, name, real_name, is_bot, deleted only | users:read |
user.updated | user_change | As above | users:read |