Gerenciar Webhooks

Eventos Disponíveis

• order.created: Disparado quando um novo pedido (carta ou email) é criado no sistema
• order.status_updated: Disparado quando o status de um pedido é alterado (processando, impresso, postado, etc.)
• tracking.updated: Disparado quando novo código de rastreio é inserido no sistema e quando novas informações de rastreamento são atualizadas pelos Correios
• rr.created: Disparado quando um novo Aviso de Recebimento (AR ou RR) é criado; o payload inclui o arquivo anexado em base64
• webhook.test: Enviado apenas quando você clica em "Testar" na lista acima. Útil para validar a conexão antes de colocar em produção.

Headers Enviados

• X-Webhook-Signature: Assinatura HMAC-SHA256 sha256=<hex> (quando configurado segredo)
• X-Webhook-Event: Tipo do evento que disparou o webhook
• X-Webhook-Delivery: ID único da tentativa de entrega
• X-Webhook-Timestamp: Data/hora da tentativa (formato Y-m-d H:i:s)
• Content-Type: application/json
• User-Agent: Escrybe-Webhooks/1.0

Política de Retentativas

• Seu endpoint deve responder com HTTP 2xx (200-299) para confirmar a entrega.
• Em caso de falha, o sistema tenta novamente automaticamente até 3 vezes com backoff exponencial: 5, 10 e 20 minutos.
• Após 3 falhas consecutivas (eventos reais, não testes), o webhook é pausado automaticamente e você recebe um email avisando.
• Você pode clicar em Retry na página de logs para reenviar manualmente um evento que falhou.
• O corpo da resposta é armazenado (até 10.000 caracteres) para ajudar você a diagnosticar o que deu errado.

Exemplo de Payload

{
  "event": "order.created",
  "timestamp": "2025-01-15 10:30:00",
  "webhook_id": 123,
  "delivery_id": 456,
  "data": {
    "id": "240115001",
    "type": "letter",
    "status": 0,
    "recipient": {
      "name": "João Silva",
      "addr1": "Rua das Flores, 123",
      "city": "São Paulo",
      "state": "SP",
      "zip": "01234-567"
    },
    "value": 15.50,
    "created_at": "2024-01-15 10:30:00",
    "paymentMethod": "invoice"
  }
}

Verificando a Assinatura (PHP)

<?php
$secret    = 'SEU_SEGREDO_AQUI';
$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');
}

// Payload é válido — processe normalmente
$data = json_decode($payload, true);
http_response_code(200);

Verificando a Assinatura (Node.js)

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

const SECRET = 'SEU_SEGREDO_AQUI';

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');

    if (!crypto.timingSafeEqual(
      Buffer.from(signature), Buffer.from(expected))) {
      return res.status(401).send('Invalid signature');
    }

    const data = JSON.parse(req.body.toString());
    res.status(200).send('ok');
  }
);

Verificando a Assinatura (Python)

import hmac, hashlib
from flask import Flask, request, abort

SECRET = b'SEU_SEGREDO_AQUI'
app = Flask(__name__)

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

    if not hmac.compare_digest(expected, signature):
        abort(401)

    data = request.get_json()
    return '', 200