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 ou e-mail registrado é criado
`order.status_updated`	Um pedido muda de status
`tracking.updated`	Um código de rastreio é atribuído, ou os Correios registram novos eventos
`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"
}

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",
    "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. 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

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.

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

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

​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

rr.created

webhook.test

Testando no homolog