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