Developer Platform

Developer Platform

Webhooks

I Webhooks consentono di inviare notifiche in tempo reale di eventi all’interno di tawk.to a servizi esterni.

Potete scegliere di inviare un evento webhook quando:

  • una chat inizia
  • una chat finisce
  • un nuovo ticket viene creato.

Un webhook consiste in:

  • Un URL che avete configurato a quale evento webhook verrà inviato
  • Uno o più eventi, che saranno pubblicati su un URL specifico
  • Una chiave segreta, che può essere utilizzata per verificare che il carico utile del webhook è stato inviato da Tawk.to

Quando un webhook viene attivato, viene fatta una richiesta POST all’URL configurato insieme ad un payload(carico utile) JSON specifico per il tipo di evento.

Reference: 

Gestione dei webhooks

I webhooks possono essere gestiti tramite il pannello di controllo tawk.to nella sezione “admin”

Eventi attualmente supportati

Le funzioni di richiamo vengono usate quando lo stato della pagina cambia. La funzione riceverà lo stato modificato che sarà online, assente o offline. Questo richiamo non è supportato nella finestra pop out della chat.

Chat:

  • Inizio
  • Fine

Ticket:

  • Crea

Politica di restituzione

Una chiamata Webhook sarà recuperata per un massimo di 12 ore se l’endpoint http risponde con tutto tranne che con un successo (2XX). Se non si riceve alcuna risposta entro 30 secondi, la chiamata sarà considerata un fallimento e sarà anche riprovata. Ad ogni evento webhook viene assegnato un ID evento. L’id dell’evento viene passato insieme ad ogni richiesta nelle intestazioni come X-Hook-Event-Id. L’id dell’evento rimarrà lo stesso in caso di ripetizioni.

Verifica della firma del webhook

Ogni evento webhook viene firmato tramite un codice di autenticazione dei messaggi (Hash-based Message Authentication Code, HMAC) utilizzando la chiave segreta webhooks. L’algoritmo HMAC-SHA1 è utilizzato per generare la firma del carico utile del webhook. La firma passa insieme ad ogni richiesta nelle intestazioni come `X-Tawk-Signature`.

Esempi:

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', $rawPost, 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 Carico utile dell’evento

Evento di inizio chat

Generato quando il primo messaggio in una chat viene inviato dal visitatore o dall’agente. Sussurri e notifiche di sistema come trigger non generano questo evento.

Carico utile dell’evento di avvio della chat

Proprieta` Tipo Descrizione
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)

Oggetto del messaggio

Proprieta` Tipo Descrizione
text String Textual representation of message
type String Message type, enum value msg, file, webrtc-call
sender Object Sender info object (See below)

Oggetto info mittente

Proprieta` Tipo Descrizione
type String Sender type, enum value agent, visitor, system

Oggetto del visitatore

Proprieta` Tipo Descrizione
name String Visitor name
email String Visitor email (Optional)
city String Visitor city
country String Visitor country in ISO 3166 format

Oggetto della proprietà

Proprieta` Tipo Descrizione
id String Property Id
name String Property name

Esempi 
{
    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'
    }
}

Evento fine chat

Generato quando una si e` conclusa

Carico utile di evento fine chat

Proprieta` Tipo Descrizione
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)

Oggetto del visitatore

Proprieta` Tipo Descrizione
name String Visitor name
email String Visitor email (Optional)
city String Visitor city
country String Visitor country in ISO 3166 format

Oggetto della proprietà

Proprieta` Tipo Descrizione
id String Property Id
name String Property name

Esempi 
{
    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'
    }
}

Evento Ticket creato

Generato quando un nuovo ticket viene creato.

Carico utile dell’evento ticket creato

Proprieta` Tipo Descrizione
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)

Oggetto richiedente ticket

Proprieta` Tipo Descrizione
name String Visitor name
email String Visitor email (Optional)

Oggetto della proprietà

Proprieta` Tipo Descrizione
id String Property Id
name String Property name

Oggetto del ticket

Proprieta` Tipo Descrizione
id String Ticket Id
humanId Number Ticket human Id
subject String Ticket subject
message String Ticket message content


Esempi 
{
    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'
    }
}
© 2024 tawk.to inc. All Rights Reserved.

Visit tawk.to