Docs / Integration API contract

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:history where one from a public channel needs channels: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 2xx answer 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 — with X-Slack-Retry-Num and X-Slack-Retry-Reason: http_error on 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 (or event_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 eventSlack event.typeDifferencesScope
message.createdmessagethread_ts present for a replychannels:history, groups:history, im:history, mpim:history
message.updatedmessagesubtype: "message_changed", with the new messagechannels:history, groups:history, im:history, mpim:history
message.deletedmessagesubtype: "message_deleted", with deleted_tschannels:history, groups:history, im:history, mpim:history
reaction.addedreaction_addedreaction is the emoji itself, not its namereactions:read
reaction.removedreaction_removedAs abovereactions:read
pin.addedpin_added—pins:read
pin.removedpin_removedNo userpins:read
channel.createdchannel_created—channels:read, groups:read
channel.updatedchannel_renameSent for any change to a channel, not only its namechannels:read, groups:read
member.joinedmember_joined_channel—channels:read, groups:read
member.leftmember_left_channel—channels:read, groups:read
user.joinedteam_joinuser carries id, name, real_name, is_bot, deleted onlyusers:read
user.updateduser_changeAs aboveusers:read

This page is made from docs/INTEGRATIONS.md.