Skip to main content

Event notifications

Event notifications are a type of webhook that listens for events in a conversation. Use them to trigger actions in external systems when these events occur. For example, an event notification can add a customer ID to a CRM system, or notify a Slack channel when a conversation escalates to a human agent.

How event notifications work​

Event notifications work like regular webhooks. You define a URL where Moveo sends event notifications with a POST request, and you select the events that trigger them.

note

A regular webhook triggers when the conversation reaches a dialog action. An event notification triggers when a specific event occurs during a conversation.

Events​

An event notification triggers when a specific event occurs during a conversation. The event_type field in the payload names the event. The X-Moveo-Event header of the request carries the same value, so you can trigger different actions per event type without parsing 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.
dialog:insightsThe insights of a completed dialog are available.
note

dialog:expired and dialog:insights are the only events that trigger event notifications.

Request payload​

Regular webhooks operate at the conversation level, and event notifications work at the account level. So the payload includes information about the account and about the event that triggered the notification.

The payload has a structure similar to the webhook payload, wrapped in an object that contains account_id and event_type. For 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​

Event notifications are notifications, not requests for data, so the webhook does not need to return a response payload. It must return a 2xx status code to acknowledge the notification.

Troubleshooting​

Duplicate events​

Webhook endpoints can occasionally receive duplicate events. To avoid processing a duplicate, use the X-Request-Id header. It contains a unique UUID for each request, for example "X-Request-Id": "a636fbdc-e257-4859-90dc-ead9dd999f12".

note

The payload (request_id) and the X-Moveo-Request-Id header also carry a request ID. Moveo uses these values internally, and they are not guaranteed to be unique per webhook request. Rely on the X-Request-Id header instead.

Timeout and retries​

Your server must respond with a 2XX response within 10 seconds of receiving a webhook event. If your server takes longer, the webhook service retries the request once, at least 5 minutes later. After that, it considers the notification a failure.

Next steps​

Last updated on