> For the complete documentation index, see [llms.txt](https://help.edgecontents.com/edgecontents/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.edgecontents.com/edgecontents/apis/webhook.md). # 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: ``` https://cliente.com/api/webhook ``` **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: ``` X-Webhook-Test: 1 ``` e também contém: ```json "test": true ``` 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: ``` Content-Type: application/json ``` e possui os seguintes headers: ``` User-Agent: EdgeContents-Webhook/1.0 X-Webhook-Event: . X-Webhook-Signature: sha256= ``` Nas requisições de teste também é enviado: ``` X-Webhook-Test: 1 ``` *** #### 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: ``` campaign_pub.add ``` 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: ``` sha256= ``` e é enviada no header: ``` X-Webhook-Signature: sha256= ``` O sistema receptor deve utilizar o mesmo secret armazenado durante a configuração do callback para gerar novamente a assinatura. O processo é: ``` Corpo bruto da requisição + Secret │ ▼ HMAC-SHA256 │ ▼ sha256= │ ▼ Compara com X-Webhook-Signature ``` 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: ``` { "status": {}, "data": [] } ``` Exemplo: ``` { "status": { "id": "68d1abc123", "username": "usuario", "date": "2026-09-28 09:30:00", "action": "add" }, "data": [ { "midia": "https://cliente.com/media/campanha.mp4", "titulo": "Campanha de teste", "data_inicial": "2026-09-28T00:00:00Z", "data_final": "2026-10-05T23:59:59Z", "duracao": "30", "status": "Active" } ] } ``` *** #### 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: ``` "status": { "id": "68d1abc123", "username": "usuario", "date": "2026-09-28 09:30:00", "action": "add" } ``` *** #### 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: ``` HTTP/1.1 200 OK Content-Type: application/json ``` ``` { "success": true } ``` 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: ``` 200–299 ``` *** #### 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**. ``` Tentativa 1 │ └── falha │ 2 segundos │ Tentativa 2 │ └── falha │ 2 segundos │ ... │ Tentativa 5 ``` 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: ``` ┌───────────────────────────────┐ │ Configurar callback │ └───────────────┬───────────────┘ │ ▼ Informar nome e URL │ ▼ Gerar novo Secret │ ▼ Salvar configuração │ ▼ Ativar eventos desejados │ ▼ ┌───────────────┐ │ Evento ocorre │ └───────┬───────┘ │ ▼ EdgeContents cria JSON │ ▼ Calcula HMAC-SHA256 │ ▼ Envia POST + headers │ ▼ ┌────────────────────┐ │ Callback do cliente│ └─────────┬──────────┘ │ ▼ Valida assinatura │ ┌──────┴──────┐ │ │ inválida válida │ │ 401 ▼ Processa payload │ ▼ HTTP 2xx ``` *** #### 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.