Configurar e inspecionar webhooks

Os webhooks são chamadas HTTP (callbacks) que o nosso servidor faz ao seu quando ocorre um evento importante de forma assíncrona (p. ex., um orçamento foi aprovado ou pago).

Registrar um endpoint

Para receber webhooks, exponha uma rota POST no seu servidor (p. ex., https://api.yourcompany.com/webhooks/cord).

1. Ative o Modo desenvolvedor em Sua conta › Preferências. A pílula Desenvolvedores aparece no canto inferior direito: abra-a (ou pressione W) e entre na aba Webhooks do Workbench (/app?wb=webhooks).
2. Clique em Adicionar endpoint e escolha os eventos: Todos os eventos, uma família completa ou eventos avulsos. A pesquisa filtra os 41 eventos por nome.
3. Digite sua URL, pública e com HTTPS, e clique em Criar endpoint. O segredo de assinatura é mostrado uma única vez: guarde-o.

Eventos disponíveis

O Cord emite eventos do ciclo de vida do orçamento e, separadamente, da fatura como objeto próprio (veja Faturamento e a API):

• quote.sent — foi enviado ao cliente.
• quote.viewed — o cliente o abriu.
• quote.approved — o cliente o aprovou.
• quote.rejected — o cliente o recusou.
• quote.updated — foi modificado e reenviado.
• quote.expired — expirou sem resposta.
• quote.deleted — um rascunho foi excluído.
• quote.paid — foi pago por completo.
• payment.partial — foi recebida uma entrada, um saldo ou uma parcela sem cobrir o total.
• payment.failed — uma cobrança recorrente falhou.
• invoice.issued, invoice.stamped — foi emitida a fatura de um orçamento: comercial fora do México ou CFDI timbrado.
• invoice.finalized, invoice.sent, invoice.paid, invoice.payment_failed, invoice.voided, invoice.marked_uncollectible, invoice.overdue — ciclo de vida de uma fatura criada como recurso próprio via /api/v1/facturas.
• quote.created, quote.approval_requested, quote.approval_decided, quote.comment_added — um orçamento foi criado, uma aprovação interna foi solicitada ou decidida, ou alguém escreveu na conversa.
• client.created, client.updated, client.deleted, product.created, product.updated, product.deleted — alterações no seu cadastro de clientes e no seu catálogo.
• task.created, task.completed, promise.created, promise.kept, promise.broken — tarefas e promessas de pagamento.
• dispute.created, dispute.closed, refund.succeeded, refund.failed, payout.paid, payout.failed, account.updated — contestações, reembolsos, repasses e alterações na sua conta de pagamentos.

Com Todos os eventos, o endpoint também recebe os que o Cord adicionar depois.

O corpo é JSON: { "id": "evt_...", "event": "quote.paid", "created_at": "...", "data": { "id", "folio", "status", "moneda", "total", "cliente", "cliente_id", "link_publico" } }. O id do evento é estável entre novas tentativas e em um reenvio manual pelo Workbench — use-o para eliminar duplicados do lado do seu servidor.

Verificação de assinatura

Valide sempre a assinatura para garantir que o evento vem do Cord. Cada entrega inclui X-Cord-Signature-V1 (com timestamp, proteção contra repetição) e, por compatibilidade, a assinatura legada X-Cord-Signature (sem timestamp). O nome do evento vai em X-Cord-Event e o id estável dele em X-Cord-Event-Id/Idempotency-Key. Se você usa Node, constructEvent de @flouviahq/node a valida por você; se preferir verificá-la manualmente em qualquer linguagem, veja o código de verificação.

Novas tentativas e inspeção

O botão Testar de cada endpoint envia uma entrega de teste: ping ou qualquer evento em que ele esteja inscrito, com dados de exemplo e "test": true no primeiro nível do corpo.

Ao expandir um endpoint, você vê o log de entregas dele (status, latência e resposta de cada tentativa) e, ao abrir uma, o que o Cord enviou e o que o seu servidor respondeu. Se uma entrega falhar, você tenta novamente a partir dali ou reenvia o evento pela aba Eventos. O histórico de entregas, as novas tentativas e o reenvio fazem parte do plano Profissional ou superior.