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.

❗️

Ping

Esse é o primeiro disparo que a Zoop faz para verificar se a URL informada é válida e pública. Caso seja válida, o status do seu webhook será "active", se não o status será "registred" ou seja, não enviaremos os webhooks com os eventos parametrizados.

{
    "id": "7dbefcb2a9614565ac92d5411669844d",
    "type": "ping",
    "resource": "event",
    "payload": {
        "object": {
            "ping": "true"
        }
    },
    "source": null,
    "name": null,
    "uri": "/v1/marketplaces/8efzad2e595343fbbe9f9725d9hc9711/events/7dbefcb2a9614565ac92d5411669844d",
    "created_at": "2020-04-01T18:21:33+0000",
    "updated_at": "2020-04-01T18:21:33+0000"
}
  1. 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 que o seu sistema de recebimento de eventos construído para receber as notificações provenientes da Zoop, 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, o marketplace será 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

Exemplo de 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 (pública) 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.

📘

NOTA

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

Updated 3 days 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.