Criar um endpoint

Visão Geral

Este endpoint cria uma nova configuração de webhook para receber notificações em tempo real sobre eventos específicos da API. O secret de assinatura (whsec_...) é retornado apenas nesta resposta — guarde-o imediatamente.

Precauções

• Seu endpoint deve responder a requisições HTTP POST.
• A URL do endpoint deve ser pública e HTTPS (URLs http:// são rejeitadas com 400).
• Sua aplicação deve responder rapidamente (timeout de entrega de 30s); processe de forma assíncrona.
• Salve o id (wbe_*) e o secret (whsec_...) retornados — o secret não é exibido novamente.

Descrição

A criação envolve um name descritivo, uma URL endpoint válida (HTTPS) e a lista events[] de tipos de evento a receber. Forneça events[] ou defina forceActive: true (um dos dois é obrigatório). Opcionalmente, você pode configurar cabeçalhos de autenticação enviados a cada disparo.

Requisição

POST /v1/webhooks

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

Corpo da Requisição

Valores em events[] são validados contra o Catálogo de Eventos. Um tipo inexistente retorna 400.

Exemplo de Requisição

{
  "name": "Webhook MyDomain",
  "endpoint": "https://webhooks.mydomain.com/selectwin",
  "events": [
    "transaction.approved",
    "transaction.pending",
    "transaction.failed"
  ],
  "metadata": {
    "team": "ops"
  }
}

Resposta

Sucesso (201 Created)

{
  "id": "wbe_01hqzvabc",
  "name": "Webhook MyDomain",
  "endpoint": "https://webhooks.mydomain.com/selectwin",
  "enabled": true,
  "events": [
    "transaction.approved",
    "transaction.pending",
    "transaction.failed"
  ],
  "forceActive": false,
  "shotsQty": 0,
  "failedShotsQty": 0,
  "lastDeliveryAt": null,
  "metadata": {
    "team": "ops"
  },
  "createdAt": "2026-06-20T20:18:05.000Z",
  "updatedAt": "2026-06-20T20:18:05.000Z",
  "secret": "whsec_abc123def456ghi789jkl012mno345pqr678stu901vwx234yz567",
  "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." },
    "create": { "href": "https://api.selectwin.io/v1/webhooks", "method": "POST", "description": "Create a new webhook." },
    "update": { "href": "https://api.selectwin.io/v1/webhooks/wbe_01hqzvabc", "method": "PUT", "description": "Update the webhook." },
    "delete": { "href": "https://api.selectwin.io/v1/webhooks/wbe_01hqzvabc", "method": "DELETE", "description": "Delete the webhook." },
    "list": { "href": "https://api.selectwin.io/v1/webhooks", "method": "GET", "description": "List all webhooks." }
  }
}

Atributos da Resposta

secret (whsec_*) só aparece no create (e no rotate-secret). As credenciais headerAuthorization/headerAuthorizationType são write-only e nunca retornam.

Erros

Melhores Práticas

1. Dê nomes descritivos aos seus webhooks para facilitar a identificação.

2. Implemente idempotência no seu endpoint; deduplique pelo id do evento.

3. Assine a menor lista de eventos que você precisa, em vez de forceActive, para evitar tráfego desnecessário.

4. Use cabeçalhos de autenticação (headerAuthorization) ou valide a assinatura HMAC para garantir a origem das requisições.

5. Salve o id e o secret imediatamente após a criação.

6. Teste seu endpoint com POST /v1/webhooks/{webhookId}/test antes de colocá-lo em produção.