Configure Events & Actions

Free offering

Events & Actions is now a free offering with one listener and one webhook with no retry.

The Events and Actions section in the Admin Portal allows for creating, editing, and deleting event listeners and specific actions that these listeners handle.

Events & Actions UI overview

E&A UI contains the Event Listeners and Actions sections.

e&a ui overview

Event Listeners

The Event Listeners section allows you to see at a glance the number and the type of event listeners you created, their status, and the actions they're connected to. Upon hovering, you can see the name of the action linked to the event listener. For more information, read how to create event listeners.

event listener section

Actions

The Actions section allows you to see at a glance the number and the type of actions you created, their status, and the event listeners they're connected to. Upon hovering, you can see the name of the event listener linked to the action. For more information, read how to create actions.

actions section

Create Event Listener

To create event listener:

  1. Open Admin Portal and choose Events & Actions.

  2. Select your app and the corresponding keyset.

  3. Click the + EVENT LISTENER button.

  4. Choose a category for your event listener.

    NameDescription
    MessagesReacts to message events.
  5. Select the type of your event listener from the dropdown list.

    NameDescription
    Message PublishTriggers an action when a message is published.
  6. Select a filter for the event listener from the dropdown list. Depending on your selection of a filter type, the flow for creating an event listener varies.

    NameDescription
    Basic FiltersPredetermined conditions triggering an action selected from the UI.
    Advanced JSONPathConditions triggering an action in a JSONPath format.
  7. Save your newly created event listener by clicking the SAVE CHANGES button.

Create filters

There are two types of filters available:

Basic filters

After choosing Basic filters, you will see two dropdown lists, Filters and Conditions, and an input field labeled Value.

  1. From the Filters dropdown list, select one of the available filters.

    NameDescription
    ChannelTrigger an action after a message is published on a specific channel.
    Sender IDTrigger an action after a message is published by a specific sender.
  2. From the Conditions dropdown list, select one of the available conditions.

    NameDescription
    Exact MatchTrigger an action only if there is an exact match.
    ContainsTrigger an action if the specified value is found.
  3. In the Value field, type the value that must meet the selected condition. For example, choosing the exact match by the channel name Matrix will create an event listener that will trigger an action on every message published in the channel named Matrix.

Advanced JSONPath

Utilizing JSONPath allows for a much more robust setup of event handlers than basic filters.

You can use JSONPath to define the following conditions to trigger an action:

User ID / UUID

User ID is also referred to as UUID/uuid in some APIs and server responses but holds the value of the userId parameter you set during initialization.

Condition nameData typeDescription
channelstringName of the channel the message was sent to.
timetokenstringMessage publish timetoken.
messageanyMessage content.
storebooleanWhether message is saved by Message Persistence.
metaanyCustom metadata.
uuidstringSender ID.

To recreate the example from Basic Filters, you can use the following JSONPath query:
$.[?(@.channel == "Matrix")]. This will trigger an action when your message is published to the channel that's named Matrix.

Create Action

  1. Create an action by clicking the + ACTIONS button.

  2. Choose the category of your action.

    NameDescription
    WebhookAllows for a third-party service integration.
  3. Put the URL of your Webhook under Configuration.

    WebHook URL

    You can also create custom headers if your webhook requires authorization, and set Webhook Retry by turning it on while creating or modifying an existing action. You can set:

    NameMin valueMax value
    Number of Retries14
    Retry Interval (in seconds)10900
  4. Pair your action with the event listener that you created previously by clicking the + EVENT LISTENER button and selecting Choose an existing event listener.

  5. Save your newly created action by clicking the SAVE CHANGES button.

Webhook payload example

The following JSON is an example of a webhook payload which is triggered when the message Wake up, Neo... is sent by Client-w5h0y on the channel Matrix.

User ID / UUID

User ID is also referred to as UUID/uuid in some APIs and server responses but holds the value of the userId parameter you set during initialization.

{
"event": {
"eventCategory": "message",
"iso8601timestamp": "2022-05-11T17:48:53Z", // <timestamp for when publish is recorded by nginx on our edge>
"subscribeKey": "sub-c-eb78cd84-test-keys-8053-0a5864604ba8",
"eventPayload": {
"meta": null, // publish meta <json>
"message": { // publish message <json>
"text": "Wake up, Neo..."
}
},
"eventId": "0b8e84d6-test-test-b478-9774bca9aff3", // id of event, in this case the publish
"eventType": "message.publish",
"channel": "Matrix", // channel on which the publish was sent
"timetoken": "16522913332159825", // pubnub publish timetoken
show all 35 lines
Last updated on