Webhooks

Webhooks empurram os eventos para o seu servidor assim que acontecem, evitando ficar consultando GET /api/v2/get. Você cadastra um endpoint, escolhe os eventos que interessam e a Escrybe faz um POST com um payload JSON nele. Os endpoints são gerenciados no painel em Configurações → Webhooks (/opcoes/webhooks), onde você também vê cada tentativa de entrega, a resposta que seu servidor deu e pode reenviar uma que falhou.

Eventos

Evento	Quando dispara
`order.created`	Um pedido de carta, e-mail registrado ou WhatsApp é criado
`order.status_updated`	Um pedido muda de status
`tracking.updated`	Cartas: um código de rastreio é atribuído, ou os Correios registram novos eventos. WhatsApp: a mensagem foi enviada, entregue, lida ou falhou, o destinatário respondeu, ou o aviso automático chegou a ele
`rr.created`	Um Aviso de Recebimento (AR/RR) fica disponível — o payload traz o arquivo
`webhook.test`	Somente quando você clica em Testar no painel

Envelope

Toda entrega tem o mesmo formato no nível de cima:

{
  "event": "order.created",
  "environment": "production",
  "timestamp": "2026-08-18 10:30:00",
  "webhook_id": 123,
  "delivery_id": 456,
  "data": { }
}

Campo	Descrição
`event`	Nome do evento, conforme a tabela acima
`environment`	`production` ou `homolog` — veja abaixo
`timestamp`	Quando o evento foi gerado, `Y-m-d H:i:s` (America/Sao_Paulo)
`webhook_id`	Cadastro de endpoint que casou com o evento
`delivery_id`	Id único desta tentativa de entrega — use para deduplicar
`data`	Corpo específico do evento

data é aditivo: campos novos podem aparecer com o tempo. Leia os campos que você usa e ignore o resto, em vez de validar contra um schema fechado.

Ambiente

environment diz qual ambiente da Escrybe produziu o evento:

Valor	Significado
`production`	Pedido real, em `app.escrybe.com.br`
`homolog`	Ambiente de testes, `homolog.escrybe.com.br`

O mesmo valor vai no header X-Webhook-Environment, então dá para desviar ou descartar um evento antes de fazer o parse do corpo.

Se você aponta os dois ambientes para o mesmo endpoint, use esse campo para separá-los. Pedidos de homologação podem ser levados por todo o ciclo de vida na mão, então produzem os mesmos eventos que a produção — é o environment que os distingue.

Headers

Header	Valor
`Content-Type`	`application/json`
`User-Agent`	`Escrybe-Webhooks/1.0`
`X-Webhook-Event`	Nome do evento
`X-Webhook-Delivery`	Id da entrega (o mesmo do `delivery_id`)
`X-Webhook-Timestamp`	Hora da tentativa, `Y-m-d H:i:s`
`X-Webhook-Environment`	`production` ou `homolog`
`X-Webhook-Signature`	`sha256=<hex>` — só quando o endpoint tem segredo

Verificando a assinatura

Quando você define um segredo, cada entrega é assinada com HMAC-SHA256 sobre o corpo bruto da requisição. Compare com uma função de tempo constante e leia o corpo antes de qualquer parse de JSON ou middleware que o reescreva.

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

$expected = 'sha256=' . hash_hmac('sha256', $payload, $secret);

if (!hash_equals($expected, $signature)) {
    http_response_code(401);
    exit('Assinatura inválida');
}

$data = json_decode($payload, true);

if (($data['environment'] ?? '') !== 'production') {
    http_response_code(200); // evento de teste — confirme, mas não processe
    exit;
}

http_response_code(200);

const crypto = require('crypto');
const express = require('express');

const app = express();
const SECRET = process.env.ESCRYBE_WEBHOOK_SECRET;

// O corpo bruto é obrigatório — express.json() reserializa e quebra a assinatura
app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.header('X-Webhook-Signature') || '';
  const expected = 'sha256=' + crypto.createHmac('sha256', SECRET)
                                     .update(req.body)
                                     .digest('hex');

  const a = Buffer.from(signature);
  const b = Buffer.from(expected);
  if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) {
    return res.status(401).send('Assinatura inválida');
  }

  const data = JSON.parse(req.body.toString());
  if (data.environment !== 'production') return res.sendStatus(200);

  res.sendStatus(200);
});

import hashlib
import hmac
import os

from flask import Flask, request

app = Flask(__name__)
SECRET = os.environ["ESCRYBE_WEBHOOK_SECRET"].encode()

@app.post("/webhook")
def webhook():
    payload = request.get_data()
    signature = request.headers.get("X-Webhook-Signature", "")
    expected = "sha256=" + hmac.new(SECRET, payload, hashlib.sha256).hexdigest()

    if not hmac.compare_digest(expected, signature):
        return "Assinatura inválida", 401

    data = request.get_json()
    if data.get("environment") != "production":
        return "", 200

    return "", 200

Entrega e retentativas

Seu endpoint precisa responder 2xx em até 30 segundos.
Uma entrega que falha é tentada de novo até 3 vezes, com backoff exponencial: 5, 10 e 20 minutos.
Após 3 falhas consecutivas em eventos reais o endpoint é pausado automaticamente e você recebe um e-mail. Reative no painel.
O corpo da resposta é armazenado (até 10.000 caracteres) para você ver o que seu servidor respondeu.
Entregas de teste nunca são repetidas e nunca contam para a pausa.

A entrega é at-least-once. Uma retentativa pode chegar depois do seu servidor já ter processado o evento — por exemplo quando ele respondeu com atraso. Use o delivery_id como chave, ou faça o handler idempotente por id do pedido e status.

Payloads

order.created

Pedidos de carta, telegrama e e-Carta:

{
  "event": "order.created",
  "environment": "production",
  "timestamp": "2026-08-18 10:30:00",
  "webhook_id": 123,
  "delivery_id": 456,
  "data": {
    "id": "260818001",
    "type": "letter",
    "status": 0,
    "shipType": "2",
    "numPages": 3,
    "value": 15.50,
    "created_at": "2026-08-18 10:30:00",
    "paymentMethod": "invoice",
    "recipient": {
      "name": "João Silva",
      "addr1": "Rua das Flores, 123",
      "addr2": "Apto 45",
      "city": "São Paulo",
      "state": "SP",
      "zip": "01234567",
      "country": "Brasil"
    },
    "sender": {
      "name_sender": "Minha Empresa LTDA",
      "addr1_sender": "Av. Paulista, 1000",
      "addr2_sender": "Sala 12",
      "city_sender": "São Paulo",
      "state_sender": "SP",
      "zip_sender": "01310100",
      "country_sender": "Brasil"
    }
  }
}

Pedidos de e-mail registrado trazem type: "email" e um data diferente:

{
  "id": "260818002",
  "type": "email",
  "status": 0,
  "recipient": { "name": "João Silva", "email": "joao@exemplo.com.br" },
  "sender": {
    "name_sender": "Minha Empresa LTDA",
    "email_sender": "contato@escrybe.com.br",
    "email_replyTo": "financeiro@minhaempresa.com.br"
  },
  "subject": "Notificação de cobrança",
  "value": 4.90,
  "created_at": "2026-08-18 10:30:00",
  "paymentMethod": "credits"
}

Pedidos de WhatsApp levam type: "whatsapp". status é o status do PEDIDO e delivery_status o estado de entrega no WhatsApp (pending, processing, sent, delivered, read, failed, cancelled) — duas coisas diferentes, nunca misturadas:

{
  "id": "ESC_WA_01M1P9H8NEK2ENZPFWEZPPRCS9",
  "type": "whatsapp",
  "status": 0,
  "delivery_status": null,
  "recipient": { "name": "João Silva", "phone": "+5511999998888", "document": "12345678900" },
  "sender": { "name_sender": "Minha Empresa LTDA", "phone": "+5514999990000", "document": "12345678000199" },
  "template": { "id": 42, "name": "notificacao_extrajudicial", "language": "pt_BR" },
  "media_filename": "notificacao.pdf",
  "value": 4.90,
  "created_at": "2026-09-16 10:30:00",
  "paymentMethod": "escrybe_credits"
}

order.status_updated

{
  "event": "order.status_updated",
  "environment": "production",
  "timestamp": "2026-08-18 14:02:11",
  "webhook_id": 123,
  "delivery_id": 457,
  "data": {
    "id": "260818001",
    "type": "letter",
    "status": { "old": 1, "new": 3 },
    "updated_at": "2026-08-18 14:02:11",
    "tracking": "RB123456789BR",
    "return_reason": null,
    "files": [
      { "type": "pdf", "created_at": "2026-08-18 10:30:00" }
    ]
  }
}

Para type: "email" o corpo traz opened e date_opened no lugar de tracking e files. return_reason só é preenchido quando o pedido vira Devolvido (status.new = 6); em qualquer outra mudança é null. É a última tentativa de entrega que falhou no rastreio dos Correios:

"return_reason": {
  "code": "BDE",
  "type": "10",
  "description": "Objeto não entregue - cliente mudou-se"
}

code e type são o par de evento dos Correios e são estáveis — use-os para classificar; description é o texto dos Correios, para exibir. Os mais comuns: BDI 26 prazo de retirada encerrado, BDE 10 mudou-se, BDE 6 desconhecido no local, BDE 21 última tentativa de entrega, BDE 8 endereço inexistente, BDE 7 endereço insuficiente, BDE 4 recusou-se a receber. Pode ser null mesmo num Devolvido, quando os Correios não informaram o motivo.

Um pedido vira Devolvido quando os Correios registram a entrega ao remetente (tracking.updated com status_delivery: "delivered_to_sender", seguido deste order.status_updated), ou quando o envelope volta fisicamente para a Escrybe. Nem toda devolução aparece no rastreio: trate status.new = 6 como o sinal definitivo.

Status de carta, telegrama e e-Carta:

`status`	Significado
0	Processando
1	Em produção
2	Créditos insuficientes
3	Impresso
4	Postado
5	Cancelado
6	Devolvido

Status de e-mail registrado:

`status`	Significado
0	Processando pagamento
1	Pago, aguardando envio
2	Créditos insuficientes
3	Enviado
4	Cancelado
5	Falha

Para type: "whatsapp" o corpo traz delivery_status em vez de tracking e files. Valores de status para pedidos de WhatsApp:

`status`	Significado
0	Processando pagamento
1	Pago, na fila de envio
2	Créditos insuficientes
5	Cancelado / falhou

tracking.updated

{
  "event": "tracking.updated",
  "environment": "production",
  "event_detail_type": "new_tracking_record",
  "timestamp": "2026-08-19 09:15:00",
  "webhook_id": 123,
  "delivery_id": 458,
  "data": {
    "id": "260818001",
    "type": "letter",
    "tracking_code": "RB123456789BR",
    "tracking_records": {
      "codObjeto": "RB123456789BR",
      "eventos": [
        {
          "codigo": "BDE",
          "dtHrCriado": "2026-08-19T09:12:00",
          "descricao": "Objeto entregue ao destinatário",
          "unidade": { "endereco": { "cidade": "São Paulo", "uf": "SP" } }
        }
      ]
    },
    "status_delivery": "delivered",
    "updated_at": "2026-08-19 09:15:00"
  }
}

event_detail_type é new_tracking_code quando o código é atribuído pela primeira vez e new_tracking_record quando os Correios registram novos eventos. tracking_records é o objeto dos Correios como eles devolvem, do evento mais novo para o mais antigo. status_delivery é vazio, delivered, going_back_to_sender ou delivered_to_sender.

tracking.updated para WhatsApp

event_detail_type é sent, delivered, read ou failed quando o WhatsApp informa o estado da sua mensagem, reply quando o destinatário a respondeu, e auto_reply_sent quando o aviso automático da plataforma chegou ao destinatário. O WhatsApp manda os statuses fora de ordem e às vezes em dobro; leia delivery_status (o estado atual) em vez de contar eventos.

{
  "event": "tracking.updated",
  "environment": "production",
  "event_detail_type": "reply",
  "timestamp": "2026-09-16 14:05:29",
  "webhook_id": 123,
  "delivery_id": 460,
  "data": {
    "id": "ESC_WA_01M1P9H8NEK2ENZPFWEZPPRCS9",
    "type": "whatsapp",
    "delivery_status": "read",
    "provider_message_id": "wamid.HBgNNTU...",
    "sent_at": "2026-09-16 10:31:02",
    "delivered_at": "2026-09-16 10:31:09",
    "read_at": "2026-09-16 13:58:40",
    "last_error": null,
    "updated_at": "2026-09-16 13:58:40",
    "reply": {
      "id": 812,
      "received_at": "2026-09-16 14:05:29",
      "from_phone": "+5511999998888",
      "from_name": "João",
      "type": "text",
      "body": "Recebi, obrigado.",
      "link_type": "context",
      "forwarded": 0,
      "identity_hash": "a1b2c3…",
      "identity_changed": false,
      "media_filename": null,
      "media_mime": null,
      "certified_timestamp": { "id": 9912, "status": "success", "hash": "…", "created_at": "2026-09-16 14:05:31" }
    }
  }
}

A resposta só chega ao seu webhook quando pôde ser vinculada a este pedido sem dúvida: o destinatário citou a sua mensagem (link_type: context) ou a sua foi a única mensagem enviada para aquele número nos últimos 30 dias (link_type: phone_match). Respostas a um número que recebeu mensagens de mais de uma conta ficam registradas na plataforma, mas nunca são atribuídas a um pedido — nem enviadas a webhook. forwarded é a marca do próprio WhatsApp (1 encaminhada, 2 encaminhada muitas vezes); identity_hash identifica o aparelho que respondeu e só vem quando a verificação de identidade está ligada no número que recebeu. certified_timestamp é o carimbo RFC 3161 da resposta; status pode ainda estar pending quando o evento dispara. Com event_detail_type: "auto_reply_sent" o objeto extra é auto_reply: { "provider_message_id", "sent_at", "to" }.

rr.created

{
  "event": "rr.created",
  "environment": "production",
  "timestamp": "2026-08-25 11:40:00",
  "webhook_id": 123,
  "delivery_id": 459,
  "data": {
    "id": "260818001",
    "type": "letter",
    "rr_type": "rr_electronic",
    "tracking_code": "RB123456789BR",
    "file": {
      "name": "260818001_rr.pdf",
      "base64": "JVBERi0xLjQKJ..."
    }
  }
}

rr_type é rr para o AR físico digitalizado e rr_electronic para o que os Correios devolvem digitalmente. file vem null quando o documento não pôde ser lido.

Este payload embute o documento inteiro em base64 e é bem maior que os outros. Garanta que seu endpoint aceita um corpo de alguns megabytes.

webhook.test

{
  "event": "webhook.test",
  "environment": "production",
  "timestamp": "2026-08-18 10:00:00",
  "webhook_id": 123,
  "delivery_id": 460,
  "data": {
    "message": "Esta é uma entrega de teste iniciada pelo usuário.",
    "webhook_id": 123,
    "webhook_name": "Meu endpoint"
  }
}

Testando no homolog

homolog.escrybe.com.br é uma cópia completa da plataforma, com banco e credenciais próprios. Os pedidos de lá permitem exercitar todos os eventos sem postar nada de verdade: na página de pedidos você move o pedido pelos status na mão e adiciona eventos de rastreio, e cada ação dispara o mesmo webhook que a produção dispararia, marcado com environment: "homolog".

E-mail registrado e WhatsApp são entregues de verdade a partir do homolog, então os destinatários precisam estar cadastrados em Whitelist de homologação (/homolog-whitelist). Quem não estiver na lista tem o envio recusado e o pedido fica com status de falha, explicando o motivo.

Peça acesso ao homolog para o suporte.

Comece aqui

Produtos

Integrações

Eventos

Envelope

Ambiente

Headers

Verificando a assinatura

Entrega e retentativas

Payloads

order.created

order.status_updated

tracking.updated

tracking.updated para WhatsApp

rr.created

webhook.test

Testando no homolog

​Eventos

​Envelope

​Ambiente

​Headers

​Verificando a assinatura

​Entrega e retentativas

​Payloads

​order.created

​order.status_updated

​tracking.updated

​tracking.updated para WhatsApp

​rr.created

​webhook.test

​Testando no homolog

Eventos

Envelope

Ambiente

Headers

Verificando a assinatura

Entrega e retentativas

Payloads

order.created

order.status_updated

tracking.updated

tracking.updated para WhatsApp

rr.created

webhook.test

Testando no homolog