Endpoints de webhook - Testar e rotacionar o segredo

#Visão Geral

Esta página cobre as duas ações operacionais sobre um webhook endpoint existente:

• Testar (POST /v1/webhooks/{webhookId}/test) — envia um ping sintético (webhook.ping) ao endpoint para verificar a fiação da integração.
• Rotacionar o segredo (POST /v1/webhooks/{webhookId}/rotate-secret) — gera um novo secret (whsec_...) de assinatura, retornado uma única vez. ⚠️ Você tem 24h para migrar, sem perder entrega: durante a janela de sobreposição as entregas vão assinadas com os dois segredos — o novo nos headers canônicos (X-Selectwin-Signature, X-Selectwin-Signature-V1) e o antigo em X-Selectwin-Signature-Previous / X-Selectwin-Signature-V1-Previous. Seu receptor pode continuar validando o header antigo até trocar a chave. Passada a janela, só o segredo novo é assinado.

#Testar o Endpoint

Dispara um evento sintético webhook.ping ao endpoint e cria um registro de entrega (dispatch) que você pode inspecionar nos Webhook Dispatches. A resposta confirma apenas que o teste foi aceito; o resultado real aparece no dispatch.

#Requisição

POST /v1/webhooks/{webhookId}/test

Cabeçalho: SelectKey: sk_live_... (ou sk_test_...). Escopo necessário: webhooks:update. Não há corpo obrigatório.

#Parâmetros de Caminho

#Resposta — Aceito (202 Accepted)

{
  "accepted": true,
  "id": "wbh_01hqzvtest"
}

O payload entregue ao seu servidor tem type: "webhook.ping" e payload.object contendo { "message": "Test ping from Selectwin", "endpointId": "wbe_..." }.

#Rotacionar o Segredo

Gera um novo secret (whsec_...) para o endpoint. O segredo retorna apenas nesta resposta — atualize-o imediatamente no seu verificador de assinatura.

#Requisição

POST /v1/webhooks/{webhookId}/rotate-secret

Cabeçalho: SelectKey: sk_live_... (ou sk_test_...). Escopo necessário: webhooks:update.

#Resposta — Sucesso (200 OK)

{
  "id": "wbe_01hqzvabc",
  "name": "Webhook MyDomain",
  "endpoint": "https://webhooks.mydomain.com/selectwin",
  "enabled": true,
  "events": ["transaction.approved", "transaction.pending"],
  "forceActive": false,
  "shotsQty": 3068,
  "failedShotsQty": 12,
  "lastDeliveryAt": "2026-06-20T17:56:33.000Z",
  "metadata": { "team": "ops" },
  "createdAt": "2026-01-26T20:18:05.000Z",
  "updatedAt": "2026-06-20T18:30:00.000Z",
  "secret": "whsec_novosegredo123456789abcdefghijklmnopqrstuvwxyz0123",
  "merchant": {
    "name": "Seller Name",
    "merchantId": "bus_1234567890",
    "isSubAccount": false
  },
  "_links": {
    "self": { "href": "https://api.selectwin.io/v1/webhooks/wbe_01hqzvabc", "method": "GET", "description": "Read a webhook." }
  }
}

Mesmos atributos do Create — inclui secret (novo). As credenciais headerAuthorization/headerAuthorizationType permanecem write-only e não retornam.

#Erros (ambas as ações)

#Melhores Práticas

1. Teste antes de produção com POST /v1/webhooks/{webhookId}/test e confira o resultado nos Dispatches.

2. Atualize o verificador assim que rotacionar o segredo — durante a janela de troca, aceite tanto o segredo antigo quanto o novo até confirmar que todas as entregas usam o novo.

3. Nunca logue o secret (whsec_...); trate-o como uma senha.

4. Para métricas e auditoria de entrega, use os Webhook Dispatches.