Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Webhook

Este documento descreve como configurar e integrar um callback de webhook ao EdgeContents, incluindo o cadastro da URL, geração do secret, autenticação e estrutura dos dados enviados.

Configuração do Webhook

A configuração dos webhooks é realizada diretamente pela página de gerenciamento de webhooks do EdgeContents.

1. Ativação dos eventos

No menu lateral do CMS, acesse Administração > Webhooks

A página apresenta os eventos disponíveis para integração.

Cada evento possui um switch que permite ativar ou desativar o envio do webhook.

Ao lado do switch existe o botão Testar, que permite verificar o envio de uma notificação para o callback configurado.

O teste utiliza a mesma URL e o mesmo secret configurados para o callback.

2. Configurar callback

Para configurar o endereço que receberá os webhooks, clique no botão Configurar callback, localizado no topo da página.

Será exibido um formulário contendo:

  • Nome da integração

  • URL do callback

  • Secret

Nome da integração

Identifica a configuração do callback e facilita sua identificação na interface.

URL do callback

É o endereço que receberá as notificações enviadas pelo EdgeContents.

A URL deve utilizar HTTPS e ser acessível publicamente pelo EdgeContents.

Exemplo:

Secret

O secret é utilizado para autenticar as requisições enviadas ao callback.

Para gerar um novo secret, clique no botão Gerar.

O secret será criado automaticamente pelo sistema e ficará oculto por padrão.

Ao lado do campo estão disponíveis as opções para:

  • Mostrar/ocultar o secret;

  • Copiar o secret para a área de transferência.

O secret gerado deve ser copiado e armazenado pelo responsável pela integração, pois será necessário para validar a assinatura das requisições recebidas.

Após preencher os campos, clique em Salvar para concluir a configuração.

3. Testar o callback

Depois de configurar a URL e o secret, o botão Testar disponível ao lado dos eventos pode ser utilizado para verificar a comunicação com o callback.

O EdgeContents enviará uma requisição de teste para a URL configurada.

A requisição de teste possui o header:

e também contém:

O resultado do teste informa se o callback foi alcançado e qual foi o código HTTP retornado pelo servidor.

4. Recebimento do Webhook

Quando um evento configurado ocorre, o EdgeContents envia uma requisição POST para a URL cadastrada.

A requisição utiliza:

e possui os seguintes headers:

Nas requisições de teste também é enviado:

5. Header X-Webhook-Event

O header X-Webhook-Event identifica o recurso e a ação que originaram a notificação.

O formato é:

Por exemplo:

O sistema receptor pode utilizar esse header para identificar qual evento deve ser processado.

6. Autenticação

As requisições são autenticadas utilizando uma assinatura HMAC-SHA256.

O EdgeContents utiliza o secret configurado no callback para gerar a assinatura a partir do corpo bruto da requisição.

A assinatura possui o seguinte formato:

e é enviada no header:

O sistema receptor deve utilizar o mesmo secret armazenado durante a configuração do callback para gerar novamente a assinatura.

O processo é:

Somente depois que a assinatura for validada o conteúdo da requisição deve ser processado.

Importante

A assinatura deve ser calculada utilizando o corpo bruto recebido pelo servidor.

Não faça json_decode() e depois json_encode() antes de calcular a assinatura, pois alterações na representação do JSON podem produzir uma assinatura diferente.

7. Estrutura do Payload

O corpo da requisição é um JSON com duas propriedades principais:

Exemplo:

8. Objeto Status

O objeto status contém informações sobre a operação que originou o webhook.

Campo

Descrição

id

Identificador único da notificação

username

Usuário responsável pela operação

date

Data e hora em que a notificação foi gerada

action

Ação executada

Exemplo:

9. Resposta do Callback

O sistema receptor deve retornar um código HTTP da faixa 2xx quando a requisição tiver sido recebida e processada corretamente.

Exemplo:

O conteúdo da resposta não é utilizado para determinar o sucesso da entrega. O EdgeContents considera a requisição entregue quando recebe um status HTTP entre:

10. Falha na Entrega

Se o callback:

  • não puder ser alcançado;

  • apresentar erro de conexão;

  • exceder o tempo limite;

  • ou retornar um código HTTP fora da faixa 2xx;

o EdgeContents considerará a entrega como falha.

O sistema realizará até 5 tentativas de entrega.

Entre as tentativas existe um intervalo de 2 segundos.

Após a quinta tentativa, a entrega será considerada como não realizada.

11. Requisitos para implementação

Para implementar um callback compatível com o EdgeContents, o sistema receptor deve:

  • disponibilizar uma URL pública;

  • utilizar HTTPS;

  • aceitar requisições POST;

  • aceitar application/json;

  • armazenar o secret gerado no cadastro;

  • validar X-Webhook-Signature;

  • utilizar HMAC-SHA256 para validar a assinatura;

  • validar X-Webhook-Event;

  • processar o JSON recebido;

  • identificar requisições de teste através de X-Webhook-Test e/ou test;

  • retornar HTTP 2xx após o processamento bem-sucedido.

12. Fluxo completo

O fluxo da integração pode ser resumido da seguinte forma:

13. Segurança

O secret deve ser tratado como uma credencial da integração.

Recomenda-se:

  • armazenar o secret de forma segura;

  • não incluir o secret no payload;

  • não enviar o secret na URL;

  • não registrar o secret em logs;

  • utilizar HTTPS;

  • validar a assinatura antes de processar o payload;

  • utilizar comparação segura para validar a assinatura.

O secret gerado na configuração é utilizado exclusivamente para autenticar as requisições através da assinatura HMAC-SHA256.

AnteriorStatus de Players

Atualizado