Skip to main content

Event notifications

Event notifications are a type of webhook that listens for events occurring in a conversation. You can use them to trigger actions in external systems based on these events. For example, event notifications can be used to add a customer ID to a CRM system or to send a notification to a Slack channel when a conversation is escalated to a human agent.

How do they work?​

Event notifications function similarly to regular webhooks. You define a URL where event notifications will be sent using a POST request and configure the specific events that should trigger them.

Unlike regular webhooks, which are triggered when a dialog action is reached, event

notifications are triggered when a specific event occurs during a conversation.

Events​

Event notifications are triggered when a specific event occurs during a conversation. You can get this information from the event_type field in the payload. It also can be found in X-Moveo-Event header of the request. This can be useful if you want to trigger different actions based on the event type without having to parse the payload.

EventTriggered when
dialog:expiredInactivity timeout's time has passed from the last user message
A dialog has not been resolved, and the session has expired.
Currently, dialog:expired is the only event that can be used to trigger event

notifications. More events will be added in the future.

Request Payload​

While regular webhooks operate at the conversation level, event notifications work at the account level. This means that the payload sent to the webhook includes information about the account and the event that triggered the notification.

The structure of the payload is similar to the webhook payload, but it is wrapped within an object containing account_id and event_type information. Below is an example:

{
  "account_id": "b8a3e9eb-b0ba-4185-850c-fd449cbc2008",
  "event_type": "dialog:expired",
  "request_id": "6ca38741-f0ce-43d2-9ba6-99894ed18208",
  "timestamp": 1742304407801,
  "events": [
    {
      "session": {
        "context": {
          "global": {
            "client_url": ""
          },
          "user": {
            "browser": "Chrome 134.0.0.0",
            "display_name": "Visitor 412",
            "language": "en",
            "locales": ["en-gb", "en-us", "en"],
            "location": {
              "city": "Athens",
              "country": "GR",
              "latitude": 37.9842,
              "longitude": 23.7353
            },
            "platform": "Mac OS 10.15.7",
            "timezone": "Europe/Athens",
            "user_id": "HD22bzXMumP_KOalmrLvD",
            "verified": false
          }
        },
        "history": [
          {
            "author_id": "HD22bzXMumP_KOalmrLvD",
            "author_type": "user",
            "responses": [
              {
                "action_id": "b1ce6303-08fc-4d0c-9e99-640d969e9b30",
                "text": "defaultstartmessage",
                "type": "text"
              }
            ],
            "timestamp": 1742304104215
          },
          {
            "author_id": "537c6e04-b69e-4658-b97f-2ca95aef91d2",
            "author_type": "brain",
            "intent_used": "greeting",
            "responses": [
              {
                "action_id": "a8c628bb-752a-4e80-b741-a75a37702bed",
                "text": "Hello! 😳\nPlease tell me who you are?",
                "type": "text"
              }
            ],
            "timestamp": 1742304106737
          }
        ],
        "is_conversation": true,
        "is_handover": false,
        "session_id": "916bac5e-8325-4860-8a41-cfa818b260e3",
        "source": {
          "channel": "web",
          "desk_id": "6634f5d1-e0ce-4ead-8e06-8d8f7972e90d",
          "integration_id": "1d093558-bac1-4954-acdd-c8d8dc05fa30",
          "is_test": true
        }
      },
      "timestamp": 1742304407521
    }
  ]
}

Response handling​

Since event notifications serve as notifications rather than requests for data, the webhook should not return any specific response payload. Instead, it must return a 2xx status code to acknowledge the receipt of the notification.

Troubleshooting​

Handling duplicate events​

Webhook endpoints might occasionally receive duplicate events. To prevent processing duplicates, use the X-Request-Id header, which contains a unique UUID for each request (e.g., "X-Request-Id": "a636fbdc-e257-4859-90dc-ead9dd999f12").

Although the request ID is also provided in the payload (request_id) and the

X-Moveo-Request-Id header, these are used internally by Moveo and are not guaranteed to be unique per webhook request. Therefore, it's advisable to rely on the X-Request-Id header.

Timeout and retries​

Your server should respond with a 2XX response within 5 seconds of receiving a webhook event. If your server takes longer than that to respond, the webhook service retries up to 5 times. After that, it terminates the connection and considers the notification a failure.

Last updated on