POST https://seu-erp.com/hooks/instvia

Webhook — Instvia → seu sistema

Configure a URL via POST /instances/{instance}/webhook. A Instvia envia um POST JSON quando a sessão muda de status ou quando mensagens entram/saem. Valide sempre a assinatura HMAC antes de processar o body.

Headers enviados

Header	Descrição
`Content-Type`	`application/json`
`X-Webhook-Event`	Tipo do evento (ex.: `message.received`).
`X-Webhook-Delivery`	UUID da entrega; permanece igual entre retries (idempotência).
`X-Webhook-Timestamp`	Unix timestamp usado na assinatura.
`X-Webhook-Signature`	HMAC-SHA256 de `{timestamp}.{raw_body}` com o secret retornado na criação do webhook.

Tipos de evento

instance.qr instance.connecting instance.connected instance.disconnected instance.reconnecting instance.error message.queued message.sent message.delivered message.read message.failed message.received

Instância conectada

Disparado quando a sessão WhatsApp fica conectada (após QR).

X-Webhook-Event instance.connected

Body (request)

{
    "id": "evt_01instance_connected",
    "event": "instance.connected",
    "created_at": "2026-08-25T18:00:00+00:00",
    "instance": {
        "id": "dac3a956-4e8b-4d76-8caf-fed98dfc8b05",
        "name": "Financeiro"
    },
    "data": {
        "status": "CONNECTED",
        "phone": "556181637717"
    }
}

Mensagem recebida

WhatsApp enviou uma mensagem para o número pareado.

X-Webhook-Event message.received

Body (request)

{
    "id": "evt_01message_received",
    "event": "message.received",
    "created_at": "2026-08-25T18:12:00+00:00",
    "instance": {
        "id": "dac3a956-4e8b-4d76-8caf-fed98dfc8b05",
        "name": "Financeiro"
    },
    "data": {
        "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
        "direction": "INBOUND",
        "type": "TEXT",
        "from": "5561991299129",
        "to": "556181637717",
        "peer": "5561991299129",
        "content": "Oi, recebi o boleto?",
        "status": "RECEIVED",
        "remote_id": "3EB0XXXX"
    }
}

Mensagem enviada

Status de uma mensagem outbound que saiu da fila e foi aceita pelo WhatsApp.

X-Webhook-Event message.sent

Body (request)

{
    "id": "evt_01message_sent",
    "event": "message.sent",
    "created_at": "2026-08-25T18:10:05+00:00",
    "instance": {
        "id": "dac3a956-4e8b-4d76-8caf-fed98dfc8b05",
        "name": "Financeiro"
    },
    "data": {
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "status": "SENT",
        "remote_id": "3EB0YYYY",
        "sent_at": "2026-08-25T18:10:05+00:00"
    }
}

Validar assinatura (PHP)

HMAC-SHA256 de {timestamp}.{raw_body} com o secret retornado na criação do webhook.

<?php
$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '';
$timestamp = $_SERVER['HTTP_X_WEBHOOK_TIMESTAMP'] ?? '';
$secret = getenv('INSTVIA_WEBHOOK_SECRET');

$expected = hash_hmac('sha256', $timestamp . '.' . $payload, $secret);
if (! hash_equals($expected, $signature)) {
    http_response_code(401);
    exit('Invalid signature');
}

$data = json_decode($payload, true);