Webhooks

Um webhook é uma notificação HTTP enviada pela Cyclopay ao endereço configurado pelo estabelecimento quando ocorre um evento relevante.

Ele permite que o e-commerce atualize pedidos e sistemas internos sem precisar consultar continuamente cada pagamento.

Por exemplo: o cliente paga por Pix, a Cyclopay recebe a confirmação e envia um evento. O e-commerce processa essa informação e atualiza o pedido.

Por que usar webhook?

Sem webhook, a aplicação precisaria consultar repetidamente cada cobrança para verificar mudanças de estado. Com a notificação, ela é avisada quando ocorre uma atualização relevante.

As consultas à API continuam sendo úteis para conferir o estado atual, investigar divergências e recuperar eventos que não foram processados.

Onde os eventos são utilizados

• Pedidos: atualizar o pagamento e liberar etapas da compra, quando confirmado.
• Financeiro e ERP: registrar recebimentos e manter os sistemas conciliados.
• Vendedores: acompanhar mudanças de situação do cadastro, quando esse tipo de evento estiver disponível.

Exemplo de integração

sequenceDiagram
    participant G as Cyclopay
    participant W as Endpoint de webhook do e-commerce
    participant Q as Fila de eventos do e-commerce
    participant S as Sistema interno do e-commerce

    G->>W: Envia notificação HTTP
    W->>Q: Registra o evento para processamento
    W-->>G: Confirma o recebimento
    Q->>S: Atualiza o pedido ou registro financeiro
    opt Conferência do estado atual
        S->>G: Consulta a Venda ou a Transação
        G-->>S: Retorna a situação atual
    end

O uso de fila é um exemplo de arquitetura. Se adotado, o evento deve ser registrado antes da confirmação de recebimento para evitar perdê-lo caso o processamento falhe.

Cuidados na implementação

• Configure uma URL HTTPS acessível pela Cyclopay.
• Confirme o recebimento rapidamente, sem executar tarefas demoradas dentro da requisição.
• Prepare o processamento para receber o mesmo evento mais de uma vez.
• Registre os identificadores necessários para relacionar evento, Venda, Transação e pedido.
• Quando houver divergência, consulte o estado atual antes de tomar decisões financeiras.
• Monitore falhas de entrega e defina como reconciliar eventos não processados.

Webhook e consulta à API