Webhooks

GET

/api/v1/webhooks

Lista os endpoints de webhook

Devolve todos os endpoints cadastrados na organização, sem paginação. Nunca inclui o segredo HMAC — só a URL, os eventos assinados, o modo de payload e o estado.

Autenticação: Sessão do painel, Chave de API
Escopo: webhooks:read
Limite: 120 requisições por minuto por organização e credencial

Requisição

curl https://crprohub.com/api/v1/webhooks \
  -H "Authorization: Bearer hub_pk_EXEMPLO_NAO_REAL"

Resposta

{
  "data": {
    "webhooks": [
      {
        "id": "b1c2d3e4-5f6a-4b7c-8d9e-0f1a2b3c4d5e",
        "name": "Endpoint principal",
        "url": "https://exemplo.com/webhooks/crprohub",
        "events": ["message.received", "message.status"],
        "payload_mode": "normalized",
        "all_channels": true,
        "status": "active",
        "consecutive_failures": 0,
        "channel_ids": [],
        "created_at": "2026-08-01T12:00:00.000Z",
        "updated_at": "2026-08-20T09:30:00.000Z"
      }
    ]
  }
}

POST

/api/v1/webhooks

Cria um endpoint; o segredo HMAC aparece uma única vez

A url precisa ser https e resolver para um endereço público — IPs privados, loopback e link-local respondem 400 WEBHOOK_URL_NOT_ALLOWED. O secret (whsec_...) usado para validar a assinatura HMAC das entregas vem só nesta resposta: não é reemitido, e perdê-lo obriga a rotacionar com /rotate-secret. all_channels: true exige channel_ids vazio; all_channels: false exige channel_ids não vazio — a combinação errada responde 400 INVALID_WEBHOOK.

Autenticação: Sessão do painel, Chave de API
Escopo: webhooks:write
Limite: 120 requisições por minuto por organização e credencial

Corpo

Parâmetro	Tipo	Obrigatório	Descrição
name	string	Sim	Nome do endpoint, de 1 a 100 caracteres.
url	string	Sim	URL https de destino, até 2048 caracteres. Precisa apontar para um host público.
event_types	lista de enum	Não	Eventos a assinar, ex.: message.received, message.status, channel.connected, template.status. Padrão lista vazia — nenhum evento chega até o endpoint até este campo ser preenchido.
payload_mode	enum	Não	normalized (formato do CRPRO Hub) ou meta_raw (payload bruto da Meta repassado como recebido). Padrão normalized.
all_channels	booleano	Não	Se true, recebe eventos de todos os canais da organização. Padrão true.
channel_ids	lista de UUID	Não	Canais aos quais o endpoint fica restrito, até 100. Só é aceito quando all_channels é false. Padrão lista vazia.

Requisição

curl -X POST https://crprohub.com/api/v1/webhooks \
  -H "Authorization: Bearer hub_pk_EXEMPLO_NAO_REAL" \
  -H "Content-Type: application/json" \
  -d '{"name":"Endpoint principal","url":"https://exemplo.com/webhooks/crprohub","event_types":["message.received","message.status"]}'

Resposta

{
  "data": {
    "webhook": {
      "id": "b1c2d3e4-5f6a-4b7c-8d9e-0f1a2b3c4d5e",
      "name": "Endpoint principal",
      "url": "https://exemplo.com/webhooks/crprohub",
      "events": ["message.received", "message.status"],
      "payload_mode": "normalized",
      "all_channels": true,
      "status": "active",
      "consecutive_failures": 0,
      "channel_ids": [],
      "created_at": "2026-08-21T12:00:00.000Z",
      "updated_at": "2026-08-21T12:00:00.000Z"
    },
    "secret": "whsec_EXEMPLO_NAO_REAL",
    "warning": "Guarde este segredo agora. Ele nao podera ser visualizado novamente."
  }
}

GET

/api/v1/webhooks/{id}

Consulta um endpoint

Um id de outro endpoint ou de outra organização responde 404. Não devolve o segredo HMAC.

Autenticação: Sessão do painel, Chave de API
Escopo: webhooks:read
Limite: 120 requisições por minuto por organização e credencial

Parâmetros de caminho

Parâmetro	Tipo	Obrigatório	Descrição
id	UUID	Sim	Identificador do endpoint de webhook.

Requisição

curl https://crprohub.com/api/v1/webhooks/WEBHOOK_UUID \
  -H "Authorization: Bearer hub_pk_EXEMPLO_NAO_REAL"

Resposta

{
  "data": {
    "webhook": {
      "id": "b1c2d3e4-5f6a-4b7c-8d9e-0f1a2b3c4d5e",
      "name": "Endpoint principal",
      "url": "https://exemplo.com/webhooks/crprohub",
      "events": ["message.received", "message.status"],
      "payload_mode": "normalized",
      "all_channels": true,
      "status": "active",
      "consecutive_failures": 0,
      "channel_ids": [],
      "created_at": "2026-08-01T12:00:00.000Z",
      "updated_at": "2026-08-20T09:30:00.000Z"
    }
  }
}

PATCH

/api/v1/webhooks/{id}

Atualiza URL, eventos ou canais do endpoint

Corpo vazio ({}) responde 400 pelo .refine do schema — envie ao menos um campo. Campos omitidos ficam como estavam. Vale a mesma regra de all_channels/channel_ids do POST: a combinação inconsistente responde 400 INVALID_WEBHOOK. status também pode ser alterado aqui, para pausar (paused) ou desabilitar (disabled) o endpoint sem removê-lo.

Autenticação: Sessão do painel, Chave de API
Escopo: webhooks:write
Limite: 120 requisições por minuto por organização e credencial

Parâmetros de caminho

Parâmetro	Tipo	Obrigatório	Descrição
id	UUID	Sim	Identificador do endpoint de webhook.

Corpo

Parâmetro	Tipo	Obrigatório	Descrição
name	string	Não	Novo nome, de 1 a 100 caracteres.
url	string	Não	Nova URL https, até 2048 caracteres, sujeita à mesma validação de host público do POST.
event_types	lista de enum	Não	Substitui a lista de eventos assinados inteira.
payload_mode	enum	Não	normalized ou meta_raw.
all_channels	booleano	Não	Alterna entre todos os canais e uma lista restrita.
channel_ids	lista de UUID	Não	Substitui a lista de canais inteira, até 100. Só é aceito quando all_channels resultante é false.
status	enum	Não	active, paused ou disabled.

Requisição

curl -X PATCH https://crprohub.com/api/v1/webhooks/WEBHOOK_UUID \
  -H "Authorization: Bearer hub_pk_EXEMPLO_NAO_REAL" \
  -H "Content-Type: application/json" \
  -d '{"status":"paused"}'

Resposta

{
  "data": {
    "webhook": {
      "id": "b1c2d3e4-5f6a-4b7c-8d9e-0f1a2b3c4d5e",
      "name": "Endpoint principal",
      "url": "https://exemplo.com/webhooks/crprohub",
      "events": ["message.received", "message.status"],
      "payload_mode": "normalized",
      "all_channels": true,
      "status": "paused",
      "consecutive_failures": 0,
      "channel_ids": [],
      "created_at": "2026-08-01T12:00:00.000Z",
      "updated_at": "2026-08-21T12:05:00.000Z"
    }
  }
}

DELETE

/api/v1/webhooks/{id}

Remove o endpoint

Remoção definitiva, não um soft delete: o registro some do banco. Não há como recuperar — crie um novo endpoint se precisar.

Autenticação: Sessão do painel, Chave de API
Escopo: webhooks:write
Limite: 120 requisições por minuto por organização e credencial

Parâmetros de caminho

Parâmetro	Tipo	Obrigatório	Descrição
id	UUID	Sim	Identificador do endpoint de webhook.

Requisição

curl -X DELETE https://crprohub.com/api/v1/webhooks/WEBHOOK_UUID \
  -H "Authorization: Bearer hub_pk_EXEMPLO_NAO_REAL"

Resposta

{
  "data": {
    "deleted": true
  }
}

GET

/api/v1/webhooks/{id}/deliveries

Lista tentativas de entrega e seus estados

Traz até 50 entregas mais recentes deste endpoint, mais recente primeiro; a rota não aceita parâmetros de paginação. status é pending, processing, retry, succeeded, dead ou canceled. Só replay (succeeded, dead ou canceled) pode ser reenviada por /replay/{deliveryId}.

Autenticação: Sessão do painel, Chave de API
Escopo: webhooks:read
Limite: 120 requisições por minuto por organização e credencial

Parâmetros de caminho

Parâmetro	Tipo	Obrigatório	Descrição
id	UUID	Sim	Identificador do endpoint de webhook.

Requisição

curl https://crprohub.com/api/v1/webhooks/WEBHOOK_UUID/deliveries \
  -H "Authorization: Bearer hub_pk_EXEMPLO_NAO_REAL"

Resposta

{
  "data": {
    "deliveries": [
      {
        "id": "c2d3e4f5-6a7b-4c8d-9e0f-1a2b3c4d5e6f",
        "event": "message.status",
        "status": "succeeded",
        "attempts": 1,
        "next_attempt_at": "2026-08-21T12:00:05.000Z",
        "last_http_status": 200,
        "last_error_code": null,
        "delivered_at": "2026-08-21T12:00:05.000Z",
        "created_at": "2026-08-21T12:00:00.000Z"
      }
    ]
  }
}

POST

/api/v1/webhooks/{id}/replay/{deliveryId}

Reenvia uma entrega específica

Só reenvia entregas já finalizadas (succeeded, dead ou canceled); uma entrega ainda pending, processing ou retry responde 404, porque já está na fila. O reenvio volta a entrega para pending — a resposta é 202, o resultado real chega depois em deliveries.

Autenticação: Sessão do painel, Chave de API
Escopo: webhooks:write
Limite: 120 requisições por minuto por organização e credencial

Parâmetros de caminho

Parâmetro	Tipo	Obrigatório	Descrição
id	UUID	Sim	Identificador do endpoint de webhook.
deliveryId	UUID	Sim	Identificador da entrega a reenviar.

Requisição

curl -X POST https://crprohub.com/api/v1/webhooks/WEBHOOK_UUID/replay/DELIVERY_UUID \
  -H "Authorization: Bearer hub_pk_EXEMPLO_NAO_REAL"

Resposta

{
  "data": {
    "delivery_id": "c2d3e4f5-6a7b-4c8d-9e0f-1a2b3c4d5e6f",
    "status": "pending"
  }
}

POST

/api/v1/webhooks/{id}/rotate-secret

Rotaciona o segredo HMAC; o novo valor aparece uma única vez

O segredo anterior é invalidado imediatamente: assinaturas calculadas com ele deixam de bater a partir desta chamada. O novo secret (whsec_...) só aparece nesta resposta — não é reemitido, e se você perdê-lo o único jeito de recuperar é rotacionar de novo.

Autenticação: Sessão do painel, Chave de API
Escopo: webhooks:write
Limite: 120 requisições por minuto por organização e credencial

Parâmetros de caminho

Parâmetro	Tipo	Obrigatório	Descrição
id	UUID	Sim	Identificador do endpoint de webhook.

Requisição

curl -X POST https://crprohub.com/api/v1/webhooks/WEBHOOK_UUID/rotate-secret \
  -H "Authorization: Bearer hub_pk_EXEMPLO_NAO_REAL"

Resposta

{
  "data": {
    "secret": "whsec_EXEMPLO_NAO_REAL",
    "warning": "O segredo anterior foi invalidado. Guarde este valor agora."
  }
}

POST

/api/v1/webhooks/{id}/test

Enfileira um evento de teste para o endpoint

Cria um evento sintético webhook.test e o enfileira como qualquer outra entrega, respeitando payload_mode do endpoint. Só funciona em endpoints com status active — endpoint pausado ou desabilitado responde 404. A resposta 202 confirma o enfileiramento, não a entrega; o resultado aparece depois em deliveries.

Autenticação: Sessão do painel, Chave de API
Escopo: webhooks:write
Limite: 10 por hora por endpoint

Parâmetros de caminho

Parâmetro	Tipo	Obrigatório	Descrição
id	UUID	Sim	Identificador do endpoint de webhook.

Requisição

curl -X POST https://crprohub.com/api/v1/webhooks/WEBHOOK_UUID/test \
  -H "Authorization: Bearer hub_pk_EXEMPLO_NAO_REAL"

Resposta

{
  "data": {
    "event_id": "d3e4f5a6-7b8c-4d9e-0f1a-2b3c4d5e6f7a",
    "delivery_id": "c2d3e4f5-6a7b-4c8d-9e0f-1a2b3c4d5e6f",
    "status": "pending"
  }
}