The concept of a webhook is simple: A webhook is an HTTP callback. It is an HTTP POST that occurs when something happens, i.e. a simple event-notification via HTTP POST.  When a webhook is configured for a certain event, the Agent Chat server will POST a message to a target URL when this event happens.

Webhooks can be used to notify an external server about certain chat events, perform extra logic, or easily integrate the Agent Chat platform with other systems.

Handshake

In order to ensure that the target server is up and can receive POST messages, a handshake is necessary before the webhook is established. This process also serves as an exchange of security keys and it can validate the authenticity of future POST event, since they are signed with the exchanged secret in the handshake process.

The following diagram shows how the handshake process is done and which data is exchanged:

To summarize, your target server must respond with a 200 status and the X-Hook-Secret it received from the Agent Chat server. Here is a PHP code sample that illustrate how the handshake occurs:

Inbenta recommends that you store the X-Hook-Secret value in your server, so you can validate the payload signature when you receive a POST event.

All event notifications are sent along with an X-Hook-Signature header, which is an HMAC (sha256) of the event data using the webhook secret exchanged before. Verification is as simple as computing the same HMAC and comparing it to the X-Hook-Signature value.