Webhooks

Visão Geral

O módulo Webhooks permite configurar notificações automáticas via HTTP para sistemas externos quando determinados eventos ocorrem na plataforma Hooked. Ao registrar um webhook, o sistema enviará uma requisição POST para a URL configurada sempre que o evento associado for disparado.

Endpoints

POST /api/webhooks

Descrição: Registra ou atualiza um endpoint de webhook para receber notificações de eventos da plataforma. Autenticação: Obrigatória

Corpo da Requisição (Request Body)

{
  "url": "https://meu-sistema.com.br/webhook/hooked",
  "eventos": [
    "pedido.criado",
    "pedido.atualizado",
    "nota_fiscal.emitida",
    "conta_pagar.vencida",
    "conta_receber.liquidada"
  ],
  "ativo": true,
  "segredo": "minha-chave-secreta-para-validacao"
}

Resposta de Sucesso

{
  "id": "uuid",
  "url": "https://meu-sistema.com.br/webhook/hooked",
  "eventos": [
    "pedido.criado",
    "pedido.atualizado",
    "nota_fiscal.emitida",
    "conta_pagar.vencida",
    "conta_receber.liquidada"
  ],
  "ativo": true,
  "dataCriacao": "2024-01-15T10:00:00Z"
}

Eventos Disponíveis

EventoDescrição
pedido.criadoNovo pedido de venda criado
pedido.atualizadoPedido de venda atualizado
nota_fiscal.emitidaNota fiscal emitida com sucesso
nota_fiscal.canceladaNota fiscal cancelada
conta_pagar.vencidaConta a pagar vencida
conta_receber.liquidadaConta a receber liquidada
pessoa.criadaNovo cadastro de pessoa criado
produto.atualizadoProduto ou serviço atualizado

Formato do Payload Enviado

Quando um evento ocorre, o sistema envia uma requisição POST para a URL registrada com o seguinte formato:

{
  "evento": "pedido.criado",
  "dataHora": "2024-01-15T10:30:00Z",
  "empresaId": "uuid",
  "dados": {
    "id": "uuid",
    "numero": 1001,
    "cliente": "João da Silva",
    "valor": 500.00
  }
}

Validação de Assinatura

Se o campo segredo for informado no cadastro, cada requisição enviada incluirá o header X-Hooked-Signature com o hash HMAC-SHA256 do payload, permitindo validar a autenticidade da notificação.

Códigos de Erro Comuns

CódigoDescrição
400URL inválida ou evento não reconhecido
401Não autorizado
409Webhook já registrado para essa URL

Exemplos de Código

cURL

curl -X POST "https://api.app.hooked.com.br/api/webhooks" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://meu-sistema.com.br/webhook/hooked","eventos":["pedido.criado","pedido.atualizado","nota_fiscal.emitida","conta_pagar.vencida","conta_receber.liquidada"],"ativo":true,"segredo":"minha-chave-secreta-para-validacao"}'

JavaScript

const response = await fetch('https://api.app.hooked.com.br/api/webhooks', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer {token}',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
  "url": "https://meu-sistema.com.br/webhook/hooked",
  "eventos": [
    "pedido.criado",
    "pedido.atualizado",
    "nota_fiscal.emitida",
    "conta_pagar.vencida",
    "conta_receber.liquidada"
  ],
  "ativo": true,
  "segredo": "minha-chave-secreta-para-validacao"
})
});
const data = await response.json();

Python

import requests

data = requests.post(
    'https://api.app.hooked.com.br/api/webhooks',
    headers={'Authorization': 'Bearer {token}'},
    json={'url': 'https://meu-sistema.com.br/webhook/hooked', 'eventos': ['pedido.criado', 'pedido.atualizado', 'nota_fiscal.emitida', 'conta_pagar.vencida', 'conta_receber.liquidada'], 'ativo': True, 'segredo': 'minha-chave-secreta-para-validacao'}
).json()

Go

import (
    "bytes"
    "net/http"
)

payload := []byte(`{"url":"https://meu-sistema.com.br/webhook/hooked","eventos":["pedido.criado","pedido.atualizado","nota_fiscal.emitida","conta_pagar.vencida","conta_receber.liquidada"],"ativo":true,"segredo":"minha-chave-secreta-para-validacao"}`)
req, _ := http.NewRequest("POST", "https://api.app.hooked.com.br/api/webhooks", bytes.NewBuffer(payload))
req.Header.Set("Authorization", "Bearer {token}")
req.Header.Set("Content-Type", "application/json")
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

PHP

$ch = curl_init('https://api.app.hooked.com.br/api/webhooks');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer {token}', 'Content-Type: application/json'],
    CURLOPT_POSTFIELDS     => json_encode([
        'url' => 'https://meu-sistema.com.br/webhook/hooked',
        'eventos' => [
            'pedido.criado',
            'pedido.atualizado'
        ],
        'ativo' => true,
        'segredo' => 'minha-chave-secreta-para-validacao'
    ]),
    CURLOPT_RETURNTRANSFER => true,
]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);

n8n

{
  "name": "Hooked API — POST /api/webhooks",
  "nodes": [
    {
      "parameters": {
        "method": "POST",
        "url": "https://api.app.hooked.com.br/api/webhooks",
        "sendHeaders": true,
        "headerParameters": {
          "parameters": [
            {
              "name": "Authorization",
              "value": "Bearer SEU_TOKEN_AQUI"
            }
          ]
        },
        "sendBody": true,
        "contentType": "json",
        "specifyBody": "json",
        "jsonBody": "{\"url\":\"https://meu-sistema.com.br/webhook/hooked\",\"eventos\":[\"pedido.criado\",\"pedido.atualizado\",\"nota_fiscal.emitida\",\"conta_pagar.vencida\",\"conta_receber.liquidada\"],\"ativo\":true,\"segredo\":\"minha-chave-secreta-para-validacao\"}",
        "options": {}
      },
      "id": "node-1",
      "name": "HTTP Request",
      "type": "n8n-nodes-base.httpRequest",
      "typeVersion": 4.2,
      "position": [
        250,
        300
      ]
    }
  ],
  "connections": {},
  "pinData": {}
}
← ConfiguraçõesOperações →