Webhooks

Los webhooks te permiten enviar notificaciones de eventos en tiempo real dentro de tawk.to a servicios externos.

Puedes elegir enviar un evento de webhook cuando:

  • comienza una charla
  • termina una charla
  • se crea un nuevo ticket

Un webhook consta de:

Cuando se activa un webhook, se realiza una solicitud POST a la URL configurada junto con una carga útil JSON específica, para el tipo de evento.

Gestión de webhooks

Los webhooks se pueden administrar a través del tablero de control tawk.to en la sección «administración».

Eventos soportados actualmente

Las funciones de recuperación se utilizan cuando cambia el estado de la página. La función recibirá el estado modificado, ya sea en línea, ausente o fuera de línea. Esta recuperación no es compatible con la ventana emergente de chat.

Charla:

  • Comienzo
  • Fin

Ticket:

  • Crear

Política de devoluciones

Una llamada de Webhook se recuperará durante un máximo de 12 horas si el punto final http responde con cualquier cosa, menos un éxito (2XX). Si no se recibe respuesta en 30 segundos, la llamada se considerará un error y se intentará nuevamente. A cada evento de webhook se le asigna un ID. La identificación del evento se envía junto con cada solicitud en los encabezados como X-Hook-Event-Id. El ID del evento seguirá siendo el mismo en caso de repeticiones.

Verificar la firma del webhook

Cada evento de webhook se firma con un código de autenticación de mensajes basado en hash (HMAC) mediante la clave secreta de webhooks. El algoritmo HMAC-SHA1 se utiliza para generar la firma de carga útil del webhook. La firma pasa junto con cada solicitud en los encabezados como «X-Tawk-Signature».

Ejemplos:

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

La carga útil del evento Webhook

Evento de inicio de chat

Se genera cuando el visitante o el agente envía el primer mensaje dentro de un chat. Los susurros y las notificaciones del sistema como disparadores o activadores no generan este evento.

Carga útil del evento al inicio del chat

Propiedad Tipo Descripción
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)

Objeto del mensaje

Propiedad Tipo Descripción
text String Textual representation of message
type String Message type, enum value msg, file, webrtc-call
sender Object Sender info object (See below)

Objeto de información del remitente

Propiedad Tipo Descripción
type String Sender type, enum value agent, visitor, system

Objeto del visitante

Propiedad Tipo Descripción
name String Visitor name
email String Visitor email (Optional)
city String Visitor city
country String Visitor country in ISO 3166 format

Objeto de la propiedad

Propiedad Tipo Descripción
id String Property Id
name String Property name

Ejemplo
{
    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 de fin de chat

Se genera cuando el chat ha finalizado

Carga útil del evento al finalizar el chat

Propiedad Tipo Descripción
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)

Objeto del visitante

Propiedad Tipo Descripción
name String Visitor name
email String Visitor email (Optional)
city String Visitor city
country String Visitor country in ISO 3166 format

Objeto de la propiedad

Propiedad Tipo Descripción
id String Property Id
name String Property name

Ejemplo
{
    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 creado con Ticket

Generado cuando se crea un nuevo ticket.

Carga útil del evento por ticket creado

Propiedad Tipo Descripción
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)

Objeto solicitante de ticket

Propiedad Tipo Descripción
name String Visitor name
email String Visitor email (Optional)

Objeto de la propiedad

Propiedad Tipo Descripción
id String Property Id
name String Property name

Objeto del ticket

Propiedad Tipo Descripción
id String Ticket Id
humanId Number Ticket human Id
subject String Ticket subject
message String Ticket message content


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