Referência de Webhooks

O middag-account recebe webhooks de entrada de serviços externos e despacha eventos de domínio internamente. Este documento cobre endpoints de webhook, verificação de payload e tipos de evento.

Endpoints de Webhooks de Entrada

Método	Endpoint	Autenticação	Descrição
POST	/webhooks/stripe	Stripe Signature	Eventos de pagamento Stripe
POST	/webhooks/hubspot	HubSpot Signature	Eventos de CRM HubSpot

URL base: /wp-json/middag-account/v1

Nenhuma autenticação JWT é utilizada. Cada webhook é validado por assinaturas específicas do serviço.

Roteamento por Empresa

Ambos os endpoints usam o header X-Middag-Company (middag_br ou middag_global) para rotear eventos para a entidade legal correta. Um único endpoint unificado por serviço atende ambas as entidades.

Eventos de Webhook Stripe

Verificação de Assinatura

Webhooks do Stripe são validados usando Stripe\Webhook::constructEvent() com o header Stripe-Signature e o segredo do endpoint de webhook. Requisições com assinatura inválida ou ausente recebem HTTP 401.

$event = \Stripe\Webhook::constructEvent(
    $payload,
    $request->getHeader('Stripe-Signature'),
    $webhookSecret
);

Eventos Processados

Evento Stripe	Ação
checkout.session.completed	Marcar pedido como pago, acionar fluxo de entitlement
invoice.paid	Registrar pagamento de fatura, atualizar assinatura
invoice.payment_failed	Sinalizar falha de pagamento, notificar organização
customer.subscription.updated	Sincronizar mudanças de status de assinatura
customer.subscription.deleted	Cancelar assinatura, suspender entitlements
charge.refunded	Processar reembolso, atualizar status do pedido

Schema de Payload (checkout.session.completed)

{
  "id": "evt_1abc...",
  "type": "checkout.session.completed",
  "data": {
    "object": {
      "id": "cs_live_...",
      "customer": "cus_...",
      "payment_status": "paid",
      "metadata": {
        "organization_id": "42",
        "quote_id": "101"
      }
    }
  }
}

Eventos de Webhook HubSpot

Verificação de Assinatura

Webhooks do HubSpot são validados usando o header X-HubSpot-Signature com o segredo do cliente HubSpot. A assinatura é um hash HMAC-SHA256 do segredo do cliente + corpo da requisição.

$expectedHash = hash('sha256', $clientSecret . $requestBody);
if (!hash_equals($expectedHash, $signatureHeader)) {
    return new WP_REST_Response(['error' => 'Invalid signature'], 401);
}

Eventos Processados

Evento HubSpot	Ação
Contact created	Sincronizar contato com usuário WordPress
Contact updated	Atualizar metadados do usuário
Deal stage changed	Atualizar status do quote vinculado
Form submission	Processar captura de lead, criar organização

Tratamento de Erros

Cenário	Resposta HTTP	Comportamento
Header de assinatura ausente	401	Rejeitar imediatamente
Assinatura inválida	401	Rejeitar, registrar tentativa
Tipo de evento desconhecido	200	Confirmar recebimento, ignorar
Falha no processamento	500	Registrar erro, retry pelo provedor

Endpoints de webhook sempre retornam 200 para eventos conhecidos processados com sucesso. Retornar non-2xx faz o provedor reenviar a entrega.

Eventos de Webhook de Saída (Eventos de Domínio)

Eventos de domínio são despachados internamente via do_action(). Consumidores externos escutam via hooks do WordPress. Consulte Pontos de Extensão para a lista completa de eventos de domínio.

Eventos-chave que acionam efeitos colaterais entre sistemas:

Evento de Domínio	Efeitos Colaterais
middag/quote/paid	Criar entitlement, atualizar deal no HubSpot
middag/entitlement/provisioned	Criar automaticamente licença, environment ou serviço
middag/entitlement/suspended	Notificar proprietário da organização, pausar downstream
middag/entitlement/cancelled	Revogar acesso downstream

Requisitos de Segurança

• Nunca processe um webhook sem validar a assinatura
• Segredos de webhook devem ser armazenados fora do webroot (variáveis de ambiente ou wp-config)
• Todo processamento de webhook é registrado para fins de auditoria
• Proteção contra replay: o Stripe oferece proteção baseada em timestamp; verifique a janela de tolerância

Relacionados

• Visão Geral da REST API -- Métodos de autenticação
• Pontos de Extensão -- Eventos internos de domínio