Mercury.ai assistants integrate into your company's ecosystem through various built-in integrations such as the Salesforce connector. However, some use cases require deeper integration into existing cloud or on-premise solutions. To make it as easy as possible to integrate with your ecosystem, the Mercury.ai platform provides a low-latency eventing system that actively informs your backend system about activity on the platform, such as received and sent messages, opened handover sessions or the status of your assistant's natural language understanding model training. To be notified about new events you provide a https endpoint on your infrastructure that is called as soon as a new event is available. To protect your users sensitive data this endpoint is required to have a valid ssl certificate.

Your webhook endpoint is required to acknowledge incoming events with a HTTP status code 200 within two seconds. If the endpoint fails to acknowledge incoming events, we will try to deliver those events in a close loop with delays of few seconds for at least a minute. If we cannot successfully deliver events to your webhook for more than a minute, we will retry the delivery every 5 minutes for 24h until the webhook endpoint is marked as disabled.

Coming soon: The API is currently in public preview and should not be used in production yet. Models and concepts can change. Additional event categories will be documented soon.


The Mercury.ai event system signs the webhook events it sends to your configured endpoints using the shared key that is part of the endpoint configuration. This signature allows your endpoint to verify that the incoming events were sent by Mercury.ai and not by any third party. Additionally to prevent timing and replay attacks a timestamp is part of the signature.

The signature is provided as a request header x-hub-signature of the following form:


Where the sig value is the HMAC-SHA256 hash of the string <t>:<raw request body>.


When a new endpoint is created, we will try to deliver a ping event to determine if the endpoint is up, SSL certificates are valid, and the endpoint responds within the required interval. The following table explains the possible status codes for your webhooks registration.

Status Comment
CREATING The event delivery system provisions resources to deliver events to your configured endpoint and attempts to deliver a ping event
OK The endpoint is operating normally
WARNING The endpoint is degraded. This could be due to single failed deliveries that could be successfully retried or due to response times that are close to the hard limit.
ERROR The endpoint is not operating. Event delivery is impossible.
DISABLED The endpoint was in ERROR state for too long so that the event delivery system gave up. Please ping your endpoint to resume operation


Currently a maximum number of three webhook receiver endpoints is allowed per project. To request a higher limit please contact support@mercury.ai.

Event Categories

Events are hierarchically structured.

Category Comment
projects Contains updates about changes in your project`s configuration, e.g. adding/removing stages
messaging Category related to incoming and outgoing messages, such as message.received and message.sent.
botusers Updates regarding channel provided information about a bot user (name, locale, ...) as well as information about the state of the conversation and results of bot-driven API calls in the users dialog context.
handover Informs about the creation/suspension of handover sessions


/v1/projects/<project id>/events

Create a new webhook receiver registration

POST /receivers/
  "name" : "Endpoint name",
  "url" : "http://my.endpoint.url",
  "secret" : "mySecretSecret",
  "subscribedEvents" : [ "messaging, ..." ]

After the endpoint configuration was successfully created, the status will be CREATING until the necessary resources are provisioned and your endpoint can be successfully contacted:

  "id" : "80009777-e5af-431a-9e3d-14f8a1009861",
  "name" : "Endpoint name",
  "url" : "http://my.endpoint.url",
  "secret" : "mySecretSecret",
  "subscribedEvents" : [ "messaging, ..." ],
  "modifiedTime" : "2020-03-31T14:54:13.513Z",
  "status" : {
    "level" : "CREATING",
    "message" : "Your webhook receiver is currently being created"

List webhook receivers

GET /receivers/

Get a specific webhook receiver endpoint

GET /receivers/<receiverId>

Ping an endpoint

Request a ping to your endpoint to determine that it is operating normally. If your endpoint was suspended because it was unreachable for a longer period of time you can use the ping operation to resume the normal operation.

POST /receivers/<receiver id>/ping

Delete a webhook receiver

DELETE /receivers/<receiver id>


Reference of event models that are contained in a webhook notifications. Each event corresponds to a set of actions on the platform that can be triggered from user interaction or by external actors such as external API integrations.

TODO ... Wrapper ...

Common field to all event types:

Field Description
timestamp Integer


Messaging events are triggered when a message is received from - or sent to a messaging channel. This also includes messages that are sent by agents through the handover system.

Field Type Description
subType Enum Can be received or sent
messageId ID The id of the message. Can be used as a reference to the message e.g. to add an interpretation to this message as training data
origin Enum The origin of the message. Possible values are BOT, USER, HANDOVER
message Message The actual message. TODO link to the message format documentation
interpretation Interpretation Interpretation of the message in terms of language and intent provided by the natural language understanding. link
user User User who sent or received the message
channel Channel Channel the message was received on or sent to

Example json:

  "timestamp" : 1586164025734,
  "projectId" : "62191466-31ac-44f6-aad0-5b1576f9f0a0",
  "type" : "messaging",
  "subType" : "received",
  "messageId" : "b25fd337-4753-4730-89dd-136c5ee4c78e",
  "origin" : "BOT",
  "message" : {
    "attachments" : [ {
      "text" : "Example text",
      "textFormat" : "PLAIN",
      "textRole" : "NONE"
    } ]
  "interpretation" : {
    "language" : "ENGLISH",
    "intent" : "Game/Intent",
    "confidence" : 0.99
  "user" : {
    "id" : "210f4c2e-67c4-4176-984c-e8bfbecb34b0",
    "nativeUserId" : "nativeId",
    "firstName" : "Example",
    "lastName" : "User"
  "channel" : {
    "id" : "70ade90b-5e49-4343-bf0d-813dbbb55ab2",
    "type" : "WEB"

Coming soon: A reference of other event models that are contained in webhook notifications.

Event Components

Events are composed of top-level properties and entities that appear in several events. These components are detailed in the following:


Information about the channel an event is related to

Field Type Description
id ID Id of the channel
type Enum The type of the channel
    "id" : "70ade90b-5e49-4343-bf0d-813dbbb55ab2",
    "type" : "WEB"


Information about a user an event is related to

Field Type Description
id ID Id of the user
nativeUserId String The id of the user that is natively used by the channel, e.e. the page specific user id for facebook messenger
    "id" : "210f4c2e-67c4-4176-984c-e8bfbecb34b0",
    "nativeUserId" : "nativeId",
    "firstName" : "Example",
    "lastName" : "User"