Webhooks

Os webhooks permitem que a Cost+ notifique o seu servidor em tempo real sempre que o estado de uma encomenda muda. Em vez de consultar a API periodicamente, fornece um URL e a Cost+ envia um pedido HTTP POST sempre que há uma atualização.

Como Funcionam os Webhooks

Especifica um webhook_url ao criar uma encomenda, ou configura um URL de webhook predefinido ao nível do projeto.
Quando o estado da encomenda muda (ex.: de new para completed), a Cost+ envia um pedido POST para o seu URL de webhook.
O seu servidor recebe o webhook, depois chama a API da Cost+ para obter os detalhes completos da encomenda.
Atualiza o seu sistema com base no estado verificado da encomenda.

Nunca confie apenas no payload do webhook para processar uma encomenda. Verifique sempre o estado da encomenda fazendo um pedido GET /v1/orders/{id}/ após receber um webhook. O webhook é um mecanismo de notificação, não uma fonte de verdade.

Payload do Webhook

O corpo do webhook é um objeto JSON contendo o tipo de evento e o ID da encomenda:

{
  "event": "status_changed",
  "order_id": "b9ae6...",
  "project_id": "proj_abc123"
}

Campo	Descrição
`event`	O tipo de evento. Atualmente `status_changed` para atualizações de encomendas.
`order_id`	O identificador único da encomenda cujo estado mudou.
`project_id`	O projeto ao qual a encomenda pertence.

Definir o URL do Webhook

Pode definir o URL do webhook de duas formas:

Por Encomenda

Inclua o campo webhook_url ao criar uma encomenda:

{
  "currency": "EUR",
  "amount": 1295,
  "webhook_url": "https://www.example.com/webhook"
}

Predefinição do Projeto

Configure um URL de webhook predefinido no seu painel Cost+ nas definições do projeto. Este URL será utilizado para todas as encomendas que não especifiquem o seu próprio webhook_url.

Mesmo que tenha uma predefinição ao nível do projeto, pode sobrepô-la por encomenda incluindo webhook_url no pedido de criação da encomenda.

Lógica de Tentativas

Se o seu servidor não responder com um código de estado 2xx, a Cost+ tenta reenviar o webhook:

Máximo de tentativas: 10
Intervalo entre tentativas: 2 minutos
Timeout da primeira tentativa: 4 segundos
Timeout das tentativas seguintes: 10 segundos

Se todas as 10 tentativas falharem, o webhook é marcado como falhado. Pode ainda obter o estado da encomenda a qualquer momento consultando a API.

Certifique-se de que o seu endpoint de webhook responde rapidamente (dentro de 4 segundos na primeira tentativa). Realize qualquer processamento demorado de forma assíncrona após devolver uma resposta 200 OK.

Boas Práticas

Verifique sempre através da API. Ao receber um webhook, chame GET /v1/orders/\{order_id\}/ para confirmar o estado atual antes de tomar ações como expedir mercadorias ou conceder acesso.
Devolva 200 rapidamente. Confirme a receção do webhook com uma resposta 200 imediatamente e processe a encomenda de forma assíncrona para evitar timeouts.
Trate duplicados. O seu endpoint de webhook pode receber o mesmo evento mais do que uma vez. Assegure-se de que a sua lógica de processamento é idempotente.
Utilize HTTPS. Utilize sempre um URL HTTPS para o seu endpoint de webhook para garantir que o payload é transmitido de forma segura.
Registe os payloads dos webhooks. Armazene os dados de webhook recebidos para fins de depuração e auditoria.

Endpoints Relacionados

Criar Encomenda — definir o webhook_url por encomenda
Atualizar Encomenda — atualizar o URL de webhook numa encomenda existente
Esquemas de Eventos Webhook — formato do payload para OrderStatusChangedEvent e TransactionStatusChangedEvent

On this page