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 Paylogos, por exemplo, uma transação é aprovada com sucesso, um evento é gerado por essa ocorrência e enviado para os webhooks cadastrados.Para utilizar a notificação de eventos por webhooks você precisa:Implementar o seu sistema de recebimento de notificações.
Cadastrar as URLs do seu sistema na Paylogos, através de APIs disponibilizadas ou via Dashboard.
Esse é o primeiro disparo que a Paylogos 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 em até 5 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": "{{ping_id}}",
"type": "ping",
"resource": "event",
"payload": {
"object": {
"ping": "true"
}
},
"source": null,
"name": null,
"uri": "/v1/events/{{event_id}}",
"created_at": "2020-04-01T18:21:33+0000",
"updated_at": "2020-04-01T18:21:33+0000"
}
É de extrema necessidade que seu sistema de recebimento de eventos seja construído para receber as notificações provenientes da Paylogos, seguindo o paradigma de integração assíncrona, recebendo as mensagens e armazenando em fila, para posterior consumo interno de seu sistema.
Vantagens na utilização#
Com o uso de notificações via webhooks é possível montar uma integração assíncrona com a Paylogos, aumentando a escalabilidade de sua plataforma.Algumas mudanças de estado dos seus recursos cadastrados na Paylogos, 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.Nossa plataforma garante que os disparos de notificações acontecem com um prazo máximo de 10 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 Paylogos.Corpo de um evento#
{
"id": "{{event_id}}",
"resource": "event",
"type": "transaction.succeeded",
"source": "API",
"payload": {
"object": {
}
},
"uri": "/v1/events/{{event_id}}",
"created_at": "2015-06-17T20:12:25",
"updated_at": "2015-06-18T07:45:02"
}
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 para consulta através de 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 existem Webhooks cadastrados a serem recebidos referentes a qualquer tipo de evento, os disparos são efetuados em até 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.A URL do seu webhook deve estar exposta (pública) para a internet, de forma que a plataforma Paylogos, 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 Paylogos efetuará novos disparos dentro de poucos instantes. Após um número máximo de 3 tentativas sem sucesso, o evento entrará em estado de falha na entrega.Uma vez que o status do evento esteja como fail (falha), o parceiro poderá solicitar através da chamada API "redisparo de eventos" o disparo dos eventos pendentes/não recebidos.Vale ressaltar que os eventos ficarão disponíveis para redisparo por um prazo de 45 dias.Timeouts#
Durante o disparo de um evento, a Paylogos espera receber uma resposta em até 1 segundo. Caso esse tempo expire, fechamos a conexão e a Paylogos irá tentar novamente o envio após 10 minutos.Aconselhamos que seja realizado um tratamento no seu sistema, garantindo que os eventos disparados em duplicidade sejam considerados apenas uma vez.
Modificado em 2025-06-04 20:31:55
