Webhooks e Rotinas

• Webhooks de saída para o lojista — as chamadas HTTPS que a plataforma dispara para o seu backend quando algo acontece (por exemplo, o status de uma transação muda).
• O sistema interno de rotinas — o mecanismo de execução em processo que busca dados da infraestrutura de processamento, atualiza modelos e, por fim, decide quando chamar o seu webhook.

​

Webhooks de saída

​

Registrando um webhook

​

Tipos de evento atualmente emitidos

​

Formato do payload

{
  "event": "transaction.update.status",
  "secret": "<o segredo que você registrou>",
  "data": {
    "id": "...",
    "status": "...",
    "amount": 1000,
    "reference_id": "ORDER-12345",
    "...": "..."
  }
}

• event — o nome canônico do evento (atualmente sempre transaction.update.status).
• secret — o valor exato que você forneceu ao criar o webhook. Use-o para autenticar a chamada.
• data — a transação serializada. Se a transação estiver vinculada a uma venda online, data.reference_id carrega a referência fornecida pelo lojista para essa venda.

​

Verificando o segredo

• A conexão TLS é a única coisa que protege o segredo em trânsito. Sempre exponha sua URL de webhook em https://.
• Se você acidentalmente expuser o segredo em logs ou no reporte de erros, faça a rotação imediatamente via PATCH no webhook com um novo valor.

import os
from flask import Flask, request, abort, jsonify

app = Flask(__name__)
WEBHOOK_SECRET = os.environ["DLPAY_WEBHOOK_SECRET"]

@app.post("/hooks/dlpay")
def dlpay_webhook():
    payload = request.get_json(silent=True) or {}

    if payload.get("secret") != WEBHOOK_SECRET:
        abort(401)

    event = payload.get("event")
    data = payload.get("data") or {}

    if event == "transaction.update.status":
        handle_transaction_update(data)
    else:
        return jsonify({"ignorado": True}), 200

    return jsonify({"ok": True}), 200


def handle_transaction_update(tx):
    transaction_id = tx["id"]
    new_status = tx["status"]
    reference_id = tx.get("reference_id")
    pass

​

Como o despacho acontece

​

Boas práticas

• Seja idempotente. Re-entregas não são garantidas, mas são possíveis — qualquer mudança de estado na mesma transação dispara outro transaction.update.status para o mesmo data.id. Use data.id (junto com data.status) como sua chave de idempotência.
• Responda rápido. O despachante te dá 5 segundos. Responda com 200 imediatamente e faça o trabalho pesado em uma rotina de segundo plano no seu lado.
• Ignore eventos desconhecidos. O conjunto de eventos despachados pode crescer ao longo do tempo. Trate qualquer evento diferente dos que você explicitamente manuseia como um no-op 200, não como erro.
• Faça a rotação do segredo via PATCH. Não há um endpoint separado de rotação — basta fazer PATCH no webhook com um novo secret. Atualize sua cópia armazenada antes de enviar a requisição e depois atualize na plataforma.
• Filtre de forma estrita. Como events é uma correspondência por substring, prefira armazenar o nome canônico exato (transaction.update.status) em vez de um fragmento (transaction.). Isso te protege no futuro contra novos eventos que compartilhem o prefixo.
• Valide o lojista do seu lado. Um único backend pode atender várias contas DL Pay; baseie seu roteamento no identificador da conta embutido na URL ou em data.account / data.seller, e não apenas no segredo.

​

O sistema interno de rotinas

​

Como as rotinas são organizadas

1. Lançadores — pequenas funções utilitárias que solicitam a execução de uma rotina à fila de jobs, passando o nome fixo e os parâmetros adicionais.
2. Funções de rotina — o trabalho propriamente dito. Recebem os parâmetros e um logger injetado.

​

Ciclo de vida e status de uma rotina

​

Deduplicação por resource_id + tipo de rotina

• O resource_id deve ser a chave natural do recurso sendo processado (por exemplo, o identificador externo da transação, o identificador do documento unificado).
• A deduplicação se aplica apenas a trabalho pendente. Assim que uma rotina muda para PROCESSANDO / SUCESSO / ERRO, o próximo lançamento com o mesmo resource_id cria um novo registro.

​

Encadeamento

​

Execução imediata vs. enfileirada

​

Webhook → Rotina → Sincronização — fluxo de ponta a ponta

​

Armadilhas comuns

• A chamada de saída não é assinada. O único marcador de autenticação é o campo secret dentro do corpo JSON. Não há cabeçalho X-Signature e não há HMAC sobre o payload. Trate o secret como uma senha e exponha sua URL de webhook apenas sobre HTTPS.
• O campo events é uma correspondência por substring. Armazenar "transaction" casará com todo evento futuro cujo nome contenha essa string. Prefira o nome canônico exato, a não ser que você queira deliberadamente uma assinatura abrangente.
• Apenas transaction.update.status é emitido hoje. Não construa caminhos de código que dependam de outros nomes de evento — a plataforma não os dispara. Se você precisar de sinais mais granulares (por exemplo, para recebíveis ou transferências), abra um pedido em vez de depender de tipos de evento não documentados.
• Não há política de retentativa por webhook. Uma entrega que falha (timeout, status diferente de 2xx, erro de rede) é registrada e descartada. A próxima mudança de estado na mesma transação dispara uma nova entrega. Construa handlers idempotentes e reconcilie via API para eventos perdidos.
• Chaves de API são tokens Bearer, nada mais. A chave de API expõe apenas name, description, key e active — não há prefix, expires_at nem escopo de permissão por chave. Permissões são concedidas no nível do lojista/usuário, não por chave.
• A deduplicação de rotinas só se aplica a registros pendentes. Se você relançar uma rotina enquanto a anterior está PROCESSANDO, um segundo registro de tarefa é criado. Isso é intencional (uma transação que mudou duas vezes em meio ao processamento deve ser buscada novamente), mas é bom saber ao ler os logs administrativos.

​

Leitura relacionada

• Criar webhook — a chamada de API para registrar uma assinatura de saída.
• Atualizar webhook — faça a rotação do segredo ou altere a URL.
• Listar webhooks — o que o lojista tem atualmente registrado.
• Fluxo da transação — como uma transação chega ao estado que dispara um webhook.
• Modelo de dados unificado — a relação entre o registro da venda e o registro unificado que o sistema de rotinas mantém em sincronia.