What are events?
Flock uses events to notify apps in real-time about interesting things like:
- App installs and uninstalls
- New messages received by the app bot
- User actions like when a button is pressed, or when a slash command is entered.
List of Events
Whenever an event is triggered, it is sent to the app in one of two ways
- Either they are sent to the Event Listener URL.
- Or they may be sent to a widget or the browser (in the form of a URL query parameter)
Some events like app.install can only be sent to the event listener URL, whereas others like client.pressButton (that are triggered in response to user actions in Flock), can be sent either to the event listener or to a widget or browser URL, depending on how the corresponding integration was configured. See Can any event be sent a to widget or browser URL? for a list of these events.
Receiving Events on the Event Listener URL
The event listener URL is an HTTPS endpoint that you provide while creating the app in the dev dashboard. Events are sent to this URL in the form of an HTTP POST request with a JSON body. The app may choose to process certain events and ignore others.
For example, if the callback URL is
https://example.com/events, the HTTP request as shown below is sent to the app.
X-Flock-Event-Token provides an event token that has been signed with the app secret. Your app can use it to verify that the request did indeed originate from Flock.
The body of the HTTP request contains an event object. Each event object contains the following fields:
name. The name of this event.
- userId. Id of the user related to this event.
- Any other custom event attributes related to this event.
Responding to Events
For most events Flock ignores the response to the HTTP request. However, for some events, a response is useful and may in fact be required. For example, the chat.generateUrlPreview event expects an attachment object in the response. This attachment is added to the message for which the preview was requested. The snippet below shows how a response to such an event might be sent.
Receiving Events on a Widget or in the Browser
The following parameters are added to the widget or browser URL:
|The event JSON, serialized into a string|
|Event token to verify that the event was sent by Flock|
|The widget type (modal, sidebar or attachment) in which the content is rendered.|
For example, if one configures an attachment picker button in the developer dashboard, when a user clicks on this button, the client.pressButton event alongwith the event token and other parameters is added to the URL like this:
List of Events sent to a Widget or Browser
Only the following events can be sent to a widget or browser.