Webhooks de Saída

Status: Planejado

O MIDDAG Account suportará webhooks de saída para notificar sistemas externos quando eventos de domínio ocorrerem. Isso permite que você construa integrações customizadas sem modificar o plugin.

Como funciona

Quando um evento significativo acontece no plugin (um entitlement é ativado, um pedido é pago, uma organização é atualizada), o plugin envia uma requisição HTTP POST para uma ou mais URLs configuradas. O sistema receptor processa o evento e toma qualquer ação que seja apropriada.

Catálogo de eventos

Eventos de organização

Evento	Disparado quando
organization.created	Uma nova organização é criada
organization.updated	Dados da organização são modificados
organization.verified	Status de verificação da organização muda

Eventos de entitlement

Evento	Disparado quando
entitlement.activated	Um entitlement torna-se ativo
entitlement.suspended	Um entitlement é suspenso
entitlement.expired	Um entitlement atinge sua expiração
entitlement.cancelled	Um entitlement é cancelado
entitlement.renewed	Um entitlement é renovado

Eventos de pedido

Evento	Disparado quando
order.created	Um novo pedido é realizado
order.paid	O pagamento de um pedido é confirmado
order.refunded	Um pedido é reembolsado

Eventos de cotação

Evento	Disparado quando
quote.created	Uma nova cotação é criada
quote.accepted	Um cliente aceita uma cotação
quote.paid	Uma cotação é paga
quote.expired	Uma cotação ultrapassa sua data de expiração

Eventos de licença

Evento	Disparado quando
license.activated	Uma licença é ativada em um site
license.deactivated	Uma licença é desativada
license.expired	Uma licença expira

Eventos de solicitação de serviço

Evento	Disparado quando
ticket.created	Uma nova solicitação de serviço é aberta
ticket.completed	Uma solicitação de serviço é resolvida
ticket.sla_breached	Uma meta de SLA é violada

Eventos de fatura

Evento	Disparado quando
invoice.issued	Uma fatura é emitida
tax_invoice.issued	Uma NFSe é emitida com sucesso
tax_invoice.failed	A emissão de uma NFSe falha

Formato do payload

Cada payload de webhook segue um envelope consistente:

{
    "event": "entitlement.activated",
    "timestamp": "2026-05-04T14:30:00Z",
    "version": "1",
    "data": {
        "id": 42,
        "code": "PLG-202605-0001",
        "organization_id": 7,
        "status": "active",
        "class": "plugin"
    }
}

Campo	Descrição
event	Tipo de evento do catálogo acima
timestamp	Timestamp ISO 8601 de quando o evento ocorreu
version	Versão do schema do payload (atualmente "1")
data	Dados específicos do evento (a entidade ou DTO relevante)

O campo data contém a mesma estrutura retornada pela REST API para a entidade correspondente.

Política de retentativa

Tentativa	Atraso	Observações
1	Imediata	Primeira tentativa de entrega
2	1 minuto	Primeira retentativa
3	5 minutos	Segunda retentativa
4	30 minutos	Terceira retentativa
5	2 horas	Retentativa final

Uma entrega é considerada bem-sucedida quando o servidor receptor responde com um código de status HTTP 2xx. Qualquer outra resposta (ou timeout) aciona uma retentativa.

Após todas as tentativas de retentativa serem esgotadas, o evento é marcado como falho. Eventos com falha são visíveis na interface admin e podem ser retentados manualmente.

Verificação de assinatura

Cada webhook de saída inclui um header de assinatura para que o sistema receptor possa verificar que a requisição originou-se do MIDDAG Account:

X-Middag-Signature: sha256=<digest hexadecimal HMAC-SHA256>

A assinatura é calculada como HMAC-SHA256(webhook_secret, corpo_bruto_da_requisição). O sistema receptor deve:

1. Ler o header X-Middag-Signature.
2. Calcular o HMAC-SHA256 do corpo bruto da requisição usando o segredo compartilhado.
3. Comparar o valor calculado com o valor do header usando uma comparação em tempo constante.
4. Rejeitar a requisição se os valores não corresponderem.

Configuração

Endpoints de webhook são configurados por organização na interface admin:

Configuração	Descrição
URL	O endpoint HTTPS que recebe os POSTs de webhook
Segredo	Segredo compartilhado para verificação de assinatura HMAC
Eventos	Quais eventos enviar (selecione do catálogo)
Ativo	Habilitar ou desabilitar o endpoint

Múltiplos endpoints podem ser configurados por organização. Cada endpoint pode se inscrever em um conjunto diferente de eventos.

Requisitos para endpoints receptores

• Devem aceitar requisições HTTP POST.
• Devem responder em até 30 segundos.
• Devem utilizar HTTPS (endpoints HTTP não são permitidos).
• Devem retornar HTTP 200 para confirmar o recebimento.
• Devem validar o header X-Middag-Signature.

Garantias de entrega

Webhooks utilizam entrega at-least-once. O mesmo evento pode ser entregue mais de uma vez (devido a retentativas ou problemas de infraestrutura). Sistemas receptores devem ser idempotentes -- processar o mesmo evento duas vezes deve produzir o mesmo resultado. Utilize a combinação event + timestamp + data.id para detectar duplicatas.