Webhooks

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.

Security

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:

t=1608018514,sig=400fdc30193720243cecbe534290

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

Status

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

Limits

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

Endpoints

/v1/projects/<project id>/events

Create a new webhook receiver registration

POST /receivers/
Body:
{
  "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>

Events

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
`projectId`

Messaging

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:

Channel

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"
}

User

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"
  }