Responding

Webhooks are often used to enable bots. To facilitate easy messaging, responses from webhooks triggered by the conversation.message event are added as messages to the conversation. If the handler wishes to post a response back into the conversation, the JSON for one or more messages can be returned as the body of the response. :

{
    "token": "<YOUR-API-KEY-HERE>"
    "messages": [{
        "text": "Small or large?"
    }]
}

Empty bodies or bodies with an empty text property will simply be ignored. Non-200 responses will be retried a reasonable number of times.

Responses will be posted using the API key user, using the user's name and avatar icon. However, if you would like to change the name on a per-response basis, simply include the message.user parameter in your response.

Webhooks Delivery

Web1on1 sends webhooks out as soon as possible. However, typical delivery timeframes vary and can not be guaranteed. Please ensure your application and integration will be able to accommodate normal webhook delivery at least an hour after the event has taken place.

You must also be prepared for events to arrive out of order, which can happen when there is a network interruption that delays the delivery of an earlier webhook. This would happen in the event that an event is retried later. These types of delays, or the order of the webhook delivery, can cause inconsistencies with your current setup. Therefore, Web1on1 recommends preparing your system to be able to accept webhooks out of order for up to an hour.

Retry Policy

If your callback URL is offline for a moment, nothing gets lost - you'll receive missed webhook calls once your callback URL is back up. A webhook call will be reattempted up to 24 hours at an exponentially increasing interval if the target responds with anything but a success (2XX) or a non-recoverable error. If no response is received within 20 seconds, the call will be considered a failure and will also be reattempted.

Non-recoverable Errors

The following status codes are deemed to be non-recoverable and Web1on1 will not reattempt a call when receiving a response with them:

Failure notifications

Top-level organizations will get a daily email of failing webhooks, if any. Non-functioning webhooks should be set to 'disabled' by an admin user.