Webhooks

Webhooks allow you to send real-time notifications of events within tawk.to to external services.

You can configure a webhook to be sent on the following events:

  • Chat starts
  • Chat ends
  • New ticket is created
A webhook consists of:

When a webhook is triggered, a POST request will be made to the URL configured along with a JSON payload specific for the event type.

Managing webhooks

Webhooks can be managed via the tawk.to dashboard in the `Admin` section.

Currently supported events

Callback functions are invoked when the page status changes. The function will receive the changed status, which will be online, away or offline. This callback is not supported in pop out chat window.

Chat:

  • Start
  • End

Ticket:

  • Create

Retry policy

A webhook call will be retried for up to 12 hours if the http endpoint responds with anything but a success (2XX). If no response is received within 30 seconds, the call will be considered a failure and will also be reattempted. Each webhook event is assigned an event Id. The event Id is passed along with each request in the headers as X-Hook-Event-Id. The event Id will remain the same in case of retries.

Verifying webhook signature

Each webhook event is signed via a Hash-based Message Authentication Code (HMAC) using the webhooks secret key. The HMAC-SHA1 algorithm is used to generate the webhook payload signature. The signature is passed along with each request in the headers as ‘X-Tawk-Signature.’

Examples:

Node.js

const WEBHOOK_SECRET = 'webhook secret key';
const crypto = require('crypto');
function verifySignature (body, signature) {
    const digest = crypto
        .createHmac('sha1', WEBHOOK_SECRET)
        .update(body)
        .digest('hex');
    return signature === digest;
};
app.post('/webhooks', function (req, res, next) {
    if (!verifySignature(req.rawBody, req.headers['x-tawk-signature'])) {
        // verification failed
    }
    // verification success
});

PHP

const WEBHOOK_SECRET = 'webhook secret key';
function verifySignature ($body, $signature) {
    $digest = hash_hmac('sha1', $body, WEBHOOK_SECRET);
    return $signature === $digest ;
}
if (!verifySignature(file_get_contents('php://input'), $_SERVER['HTTP_X_TAWK_SIGNATURE'])) {
    // verification failed
}
// verification success

Ruby

WEBHOOK_SECRET = 'webhook secret key';
post '/payload' do
    request.body.rewind
    body = request.body.read
    signature = request.env['HTTP_X_TAWK_SIGNATURE']
    unless verifySignature(body, signature))
        // verification failed
    end
    // verification success
end
def verifySignature(body, signature)
    digest = OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new('sha1'), WEBHOOK_SECRET, body)
    return digest == signature
end

Webhook event payload

Chat start event

Generated when the first message in a chat is sent by visitor or agent. Whispers and system notifications like triggers do not generate this event.

Chat start event payload

Property Type Description
event String Event name `chat:start`
chatId String Chat Id
time String Event generation date time in JSON format
message Object Message object (See below)
visitor Object Visitor object (see below)
property Object Property object (see below)

Message object

Property Type Description
text String Textual representation of message
type String Message type, enum value msg, file, webrtc-call
sender Object Sender info object (See below)

Sender info object

Property Type Description
type String Sender type, enum value agent, visitor, system

Visitor object

Property Type Description
name String Visitor name
email String Visitor email (Optional)
city String Visitor city
country String Visitor country in ISO 3166 format

Property object

Property Type Description
id String Property Id
name String Property name

Example
{
    event: 'chat:start',
    chatId: '70fe3290-99ad-11e9-a30a-51567162179f',
    time: '2019-06-28T14:03:04.646Z',
    message : {
        text : 'Sample message',
        type : 'msg',
        sender : {
            type : 'visitor'
        }
    },
    visitor: {
        name: 'V1561719148780935',
        email : 'hello@test.com',
        city: 'jelgava',
        country: 'LV'
    },
    property: {
        id: '58ca8453b8a7e060cd3b1ecb',
        name: 'Bobs Burgers'
    }
}

Chat end event

Generated when a chat has ended

Chat end event payload

Property Type Description
event String Event name chat:end
chatId String Chat Id
time String Event generation date time in JSON format
visitor Object Visitor object (see below)
property Object Property object (see below)

Visitor object

Property Type Description
name String Visitor name
email String Visitor email (Optional)
city String Visitor city
country String Visitor country in ISO 3166 format

Property object

Property Type Description
id String Property Id
name String Property name

Example
{
    event: 'chat:end',
    chatId: '70fe3290-99ad-11e9-a30a-51567162179f',
    time: '2019-06-28T14:04:08.718Z',
    visitor: {
        name: 'V1561719148780935',
        email : 'hello@test.com',
        city: 'jelgava',
        country: 'LV'
    },
    property: {
        id: '58ca8453b8a7e060cd3b1ecb',
        name: 'Bobs Burgers'
    }
}

Ticket created event

Generated when a new ticket is created.

Ticket create event payload

Property Type Description
event String Event name `ticket:create`
time String Event generation date time in JSON format
requester Object Ticket requester object (see below)
property Object Property object (see below)
ticket Object Ticket object (see below)

Ticket requester object

Property Type Description
name String Visitor name
email String Visitor email (Optional)

Property object

Property Type Description
id String Property Id
name String Property name

Ticket object

Property Type Description
id String Ticket Id
humanId Number Ticket human Id
subject String Ticket subject
message String Ticket message content


Example
{
    event: 'ticket:create',
    time: '2019-06-28T14:07:13.512Z',
    property: {
        id: '58ca8453b8a7e060cd3b1ecb',
        name: 'Bobs Burgers'
    },
    requester: {
        name: 'Martins',
        email: 'martins@tawk.to',
        type: 'agent'
    },
    ticket: {
        id: '02598050-99ae-11e9-8887-97564881b95b',
        humanId: 3,
        subject: 'Testing',
        message: 'Once more through the breach'
    }
}