Notificações e eventos (Webhook)

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 do seu sistema na Zoop, através de APIs disponibilizadas ou via 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.

Caso não receba o ping dentro de 3 minutos, orientamos que faça uma nova consulta na API de "Listar webhooks por marktplace" e na chave "status" será possível identificar se o mesmo foi criado com sucesso.

{
	"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"
}

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.

📘

É de extrema necessidade que o seu sistema de recebimento de eventos construído para receber as notificações provenientes da Zoop, seguindo o paradigma de integração assíncrona, recebendo as mensagens e armazenando-as em filas para posterior consumo interno de seu sistema.

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 5 minutos, 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 5 minutos após a geração. Essa espera se dá para que o seu ERP 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.

❗️

Importante

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 a Zoop irá tentar novamente o envio após 10 minutos.

❗️

Importante

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