API Webhooks

Documentação dos endpoints para gerenciamento de webhooks da API.

Para entender o fluxo completo de como receber e processar as notificações no seu servidor (validação do Authorization, retentativas, idempotência), veja Como receber webhooks. Para uma visão geral do fluxo de conexão e quando os webhooks entram em cena, veja Fluxo de conexão.

Endpoints

Criar webhook

Cria um novo webhook para receber notificações de eventos.

Método e URL:

POST /v1/webhooks

Parâmetros do corpo da requisição:

• url (string, obrigatório): URL de destino onde o webhook será enviado (deve ser HTTPS)
• secret (string, obrigatório): Chave secreta usada para assinar as requisições do webhook

Resposta de sucesso (201):

{
  "status": "success",
  "data": {
    "id": "uuid",
    "url": "https://exemplo.com/webhook",
    "secret": "chave_secreta",
    "createdAt": "timestamp",
    "updatedAt": "timestamp"
  }
}

Campos da resposta:

• id: Identificador único do webhook
• url: URL de destino configurada
• createdAt: Data de criação do webhook
• updatedAt: Data da última modificação

Listar webhooks

Retorna a lista de todos os webhooks configurados para sua conta.

Método e URL:

GET /v1/webhooks

Resposta de sucesso (200):

{
  "status": "success",
  "data": {
    "webhooks": [
      {
        "id": "uuid",
        "url": "https://exemplo.com/webhook",
        "createdAt": "timestamp",
        "updatedAt": "timestamp"
      }
    ]
  }
}

Campos da resposta:

• webhooks: Array contendo os webhooks
  • id: Identificador único do webhook
  • url: URL de destino do webhook
  • createdAt: Data de criação
  • updatedAt: Data da última modificação

Buscar webhook específico

Retorna os detalhes de um webhook específico.

Método e URL:

GET /v1/webhooks/:id

Parâmetros da URL:

• id (UUID v7, obrigatório): Identificador único do webhook

Resposta de sucesso (200):

{
  "status": "success",
  "data": {
    "id": "uuid",
    "url": "https://exemplo.com/webhook",
    "createdAt": "timestamp",
    "updatedAt": "timestamp"
  }
}

Campos da resposta:

• id: Identificador único do webhook
• url: URL de destino do webhook
• createdAt: Data de criação
• updatedAt: Data da última modificação

Resposta de erro (404):

{
  "status": "error",
  "message": "Webhook not found"
}

Atualizar webhook

Atualiza a configuração de um webhook existente.

Método e URL:

PUT /v1/webhooks/:id

Parâmetros da URL:

• id (UUID v7, obrigatório): Identificador único do webhook

Parâmetros do corpo da requisição:

• url (string, obrigatório): Nova URL de destino do webhook
• secret (string, obrigatório): Nova chave secreta para assinatura

Resposta de sucesso (200):

{
  "status": "success",
  "data": {
    "id": "uuid",
    "url": "https://nova-url.com/webhook",
    "createdAt": "timestamp",
    "updatedAt": "timestamp"
  }
}

Campos da resposta:

• id: Identificador único do webhook
• url: Nova URL de destino configurada
• createdAt: Data de criação original
• updatedAt: Data da última modificação

Remover webhook

Remove um webhook da sua conta.

Método e URL:

DELETE /v1/webhooks/:id

Parâmetros da URL:

• id (UUID v7, obrigatório): Identificador único do webhook

Resposta de sucesso (200):

{
  "status": "success",
  "message": "Webhook deleted successfully"
}

Campos da resposta:

• status: Status da operação (sempre "success" em caso de sucesso)
• message: Mensagem confirmando a remoção

Resposta de erro (404):

{
  "status": "error",
  "message": "Webhook not found."
}

Observações

• Todos os endpoints requerem autenticação
• Os IDs devem seguir o formato UUID v7
• As URLs dos webhooks devem SEMPRE usar HTTPS para garantir a segurança