Sobre os Webhooks

Sobre o produto

Notificação de eventos através de webhooks

Visão Geral

Webhooks (também conhecidos como HTTP Callbacks) são uma forma de se registrar para receber informações úteis em uma URL específica de sua escolha.

Quando ocorre uma alteração no estado de um recurso dentro das plataformas da Zoop (por exemplo, uma transação é aprovada com sucesso ou um estabelecimento comercial é aprovado pelo fluxo manual de credenciamento), um evento é gerado por essa ocorrência e enviado para os webhooks cadastrados.

Para utilizar a notificação de eventos por webhooks você precisa:

  1. Implementar o seu sistema de recebimento de notificações
  2. Cadastrar as URLs desse sistema na Zoop, através das APIs disponibilizadas ou através do Dashboard.
  3. Quando ocorrer uma ação em cima dos seus recursos dentro da plataforma da Zoop, as notificações serão disparadas de acordo com os webhooks cadastrados

Sugerimos fortemente que o sistema de recebimento de notificações construído para receber as nossas notificações siga o paradigma de integração assíncrona, recebendo as mensagens e armazenando-as em filas para posterior consumo interno de seu sistema. Isso aumenta a disponibilidade e facilidade de manutenção e recuperação dessas integrações.

Vantagens na utilização

Escalabilidade

Com o uso de notificações via webhooks é possível montar uma integração assíncrona com a Zoop, aumentando a escalabilidade de sua plataforma.

Transparência

Algumas mudanças de estado dos seus recursos cadastrados na Zoop acontecem mesmo que nenhuma chamada tenha sido realizada, como por exemplo, habilitação de vendedores ou cobrança de uma assinatura recorrente. Com os webhooks devidamente cadastrados, você é notificado de todos esses acontecimentos.

Disponibilidade

Nossa plataforma garante que os disparos de notificações acontecem com um prazo máximo de 1 minuto, contados a partir do horário da ocorrência que originou o evento.

Anatomia de um evento

Como, quando e quais eventos são disparados pela Zoop

Corpo de um evento

 {
    "id": "abd9af10094d49ebbf800d4b497cd669",
    "resource": "event",
    "type": "transaction.succeeded",
    "source": "API",
    "payload": {
        "object": {
            //...
        }
    },
    "uri": "/v1/marketplaces/0162893710a6495e86542eeff192baa1/events/abd9af10094d49ebbf800d4b497cd669",
    "created_at": "2015-06-17T20:12:25",
    "updated_at": "2015-06-18T07:45:02"
}

Os dados do campo payload.object varia de acordo com o campo type, uma vez que esse conteúdo é referente ao estado final do recurso após a conclusão da ação que disparou o evento.

Como funcionam os disparos

Geração dos eventos

Independente de ter webhooks cadastrados, os eventos são gerados sempre que a sua ocasião de disparo é satisfeita. Esses eventos ficam disponíveis nas nossas APIs de listagem de eventos, apesar de desencorajarmos fortemente a utilização das APIs de leitura dos eventos através de crawling.

Disparo dos webhooks

Quando um evento é gerado, e existe webhooks cadastrados para receber tal tipo de evento, os disparos são agendados para 20 segundos após a geração. Essa espera se dá para que o seu sistema consiga finalizar as tarefas necessárias após a resposta da chamada que gerou o evento, evitando que os disparos sejam realizados antes de uma possível propagação de dados entre os componentes de software que compõem o seu sistema.

A URL do seu webhook deve estar exposta para a internet, de forma que a plataforma da Zoop a alcance e consiga enviar os eventos.

Fluxo de retentativas de disparos

Uma vez que a primeira tentativa de entrega não obtém sucesso, a Zoop efetuará novos disparos dentro de poucos instantes. Após um número máximo de 3 tentativas sem sucesso, o evento entra em estado de falha na entrega.

Timeouts

Durante o disparo de um evento para um de seus webhook, a Zoop espera receber uma resposta em até 1 segundo. Caso esse tempo expire, fechamos a conexão e retentaremos o envio após 10 minutos.

Aconselhamos fortemente que você realize um tratamento no seu sistema, garantindo que os eventos disparados em duplicidade sejam considerados apenas uma vez.

Updated about a month ago


Sobre os Webhooks


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.