Pular para o conteúdo
Entrar Lista de espera

Criar webhook

POST /v1/webhooks escopo admin

Cria um webhook. A url precisa ser https e de um host público (IP privado, localhost e endereços de metadados de nuvem são recusados com unsafe_url). O secret de assinatura volta UMA vez. No máximo 10 por workspace.

CabeçalhosAuthorization: Bearer praeko_… e X-Praeko-Contract: en. Sempre envie os dois.

Parâmetros

Nome Onde Descrição
Idempotency-Key cabeçalho Chave de idempotência (1 a 255 caracteres visíveis, por exemplo um UUID). Repetir o MESMO pedido com a mesma chave, em até 24 h, devolve a resposta guardada (com Idempotent-Replayed: true) sem executar de novo; outro pedido com a mesma chave dá 422 idempotency_key_reuse; um pedido ainda em andamento dá 409 idempotency_in_progress. Erros 5xx não são guardados. A chave vale por workspace e por rota. Veja Repetir uma requisição.

Corpo da requisição

JSON. Campos obrigatórios precisam ir; os outros podem ser omitidos.

Campo Tipo Descrição
url obrigatório texto Endereço que recebe os eventos. Precisa ser https, de um domínio público (sem usuário e senha; IP privado, localhost e nomes internos são recusados com unsafe_url). Até 2048 caracteres.
events (opcional) string[] Eventos que disparam o webhook. Pelo menos um. Valores: post.sent, post.failed, post.scheduled-fail; padrão: post.sent, post.failed.
active (opcional) verdadeiro/falso Se o webhook começa ligado. Padrão: true.
Exemplo de corpo
{
  "url": "https://exemplo.com.br/hooks/praeko",
  "events": [
    "post.sent",
    "post.failed"
  ],
  "active": true
}

Exemplo

curl -X POST "https://praeko.app/v1/webhooks" \
  -H "Authorization: Bearer $PRAEKO_KEY" \
  -H "X-Praeko-Contract: en" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://exemplo.com.br/hooks/praeko",
  "events": [
    "post.sent",
    "post.failed"
  ],
  "active": true
}'

Resposta

Status de sucesso Quando
200 Sucesso.
Resposta 200
{
  "id": "wh_01KA3X4D8P6TQ1VZ0C7MH2NB5R",
  "url": "https://exemplo.com.br/hooks/praeko",
  "events": [
    "post.sent",
    "post.failed"
  ],
  "active": true,
  "secretHint": "whsec_…k3Qw",
  "consecutiveFailures": 0,
  "createdAt": "2026-11-07T14:02:11.482Z",
  "updatedAt": "2026-11-07T14:02:11.482Z",
  "secret": "whsec_8vN2xQe4L1mTz7Hc0Yb5Wd3KfRj6PaUo9GtSi2XnVEw",
  "warning": "guarde este segredo agora: ele não aparece de novo"
}

Erros

Status code Quando
400 empty_body O corpo veio vazio.
400 invalid_json O corpo não é um objeto JSON.
413 body_too_large O corpo passa de 1 MB.
422 invalid_field url ausente ou events vazio/desconhecido.
422 unsafe_url A url não é https, aponta para rede privada ou localhost.
409 webhook_limit_reached Já são 10 webhooks neste workspace.
422 idempotency_key_reuse A Idempotency-Key já foi usada com outro pedido (método, caminho, query ou corpo diferentes).
409 idempotency_in_progress Um pedido com a mesma Idempotency-Key ainda está em andamento (repita em instantes).
409 idempotency_response_too_large A resposta original passou de 256 KB e não foi guardada; consulte o recurso por GET.

Erros de qualquer rota

Status code Quando
401 unauthorized Faltou o cabeçalho Authorization: Bearer ….
401 invalid_api_key A chave não existe.
401 revoked_api_key A chave foi revogada.
401 expired_api_key A chave expirou.
403 forbidden O escopo da chave não basta para esta rota (veja o selo de escopo).
429 rate_limited Passou do limite de requisições por minuto.

O corpo de todo erro é { "error": { "code", "message", "details"? } }. Veja todos os códigos.

Testar

Testar

O teste ao vivo usa a sua chave e a sua conta. Para quem não entrou, fica desligado.

Entre para testar
Dúvida ou erro nesta página? contato@praeko.appVer .md

Digite para buscar páginas, rotas e códigos de erro.