Endpoints de webhook

Diga ao WhatIsUp.dev para onde entregar as notificações de evento. Um cliente pode ter múltiplos endpoints (URLs diferentes para subconjuntos diferentes de eventos). Um canal pode ser a origem de eventos para múltiplos endpoints, e um endpoint pode assinar múltiplos canais — é um relacionamento muitos-para-muitos.

Modelo conceitual

Endpoints descrevem uma assinatura: para onde enviar, quais eventos enviar, e o secret de assinatura usado no HMAC. Os registros de entrega de fato estão em Entregas de webhook.

api_key → customer ──┬── channel ◄───┐
                     │                 │
                     └── webhook_endpoint
                              │
                              └── webhook_delivery (per event)

Listar endpoints

Retorna todos os endpoints do cliente autenticado.

Criar um endpoint

curl -sX POST "$WHATISUP_API/v1/webhook-endpoints" \
  -H "Authorization: Bearer $WHATISUP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://api.acme.dev/whatisup/webhook","events":["message.received","message.sent"],"channel_id":"8d653c66-e4ff-43ee-97da-3de5ad5680d4"}'

Todo endpoint tem o seu próprio secret de assinatura. Passe signing_secret pra escolher o valor, ou omita e o gateway gera um secret whsec_… exclusivo pra aquele endpoint. A resposta 201 devolve o secret nos dois casos — é a única resposta que traz ele. Depois disso você pode lê-lo de novo quando quiser via GET /v1/webhook-endpoints/{id}/signing-secret, que retorna { signing_secret, is_default }; is_default é sempre false e existe só por compatibilidade. Leituras normais (GET, PATCH) expõem apenas o booleano has_custom_signing_secret.

Atualizar um endpoint

Não existe flag rotate_secret. Para rotacionar, faça PATCH no endpoint com um novo signing_secret (string de 16–255 caracteres, valor seu):

{ "signing_secret": "whsec_um-novo-secret-de-32-ou-mais-chars" }

Passe "signing_secret": null para o gateway gerar um secret novo pro endpoint (leia com a rota signing-secret acima). Qualquer das duas mudanças vale a partir da próxima entrega — o secret antigo para de funcionar na hora, então atualize seu receptor primeiro.

Testar um endpoint

Duas rotas disparam uma entrega sintética assinada. As duas devolvem o mesmo superconjunto, então um parser só lê as duas:

• POST /v1/webhook-endpoints/test — testa qualquer URL, guardada ou não. Corpo: { "url": "..." }.
• POST /v1/webhook-endpoints/:id/test — testa um endpoint guardado com o secret real dele.

{
  "ok": true,
  "status": "success",
  "outcome": "success",
  "http_status": 200,
  "latency_ms": 372,
  "elapsed_ms": 372,
  "signed_with": "endpoint",
  "endpoint_id": "0f2c5ad1-8b47-4e93-a5d2-6c81e04fb7a9"
}

signed_with: "gateway_default" significa que não temos secret guardado para aquela URL, então o teste foi assinado com um secret aleatório de uso único: um 401 de volta é esperado e não quer dizer "seu receptor está quebrado". Salve o endpoint e teste com /:id/test pra assinar com o secret real dele.

Excluir um endpoint

Retorna 204 No Content. Entregas em andamento que já foram enfileiradas vão falhar contra o endpoint agora excluído e esgotar o orçamento de retentativas normalmente.