tokeflow.com
DocumentaçãoReferência da APIDashboardsSDKsChangelog

Endpoints de webhook

Registre e gerencie endpoints de webhook programaticamente — crie configurações, inspecione entregas e rotacione o segredo de assinatura usado para verificar eventos.

Um endpoint de webhook é uma URL para a qual a Tokeflow entrega eventos assinados, além da configuração que o rege: quais tipos de evento ele assina, se está ativo, e o segredo de assinatura usado para provar que cada entrega veio da Tokeflow.

Esses endpoints permitem que você gerencie essa configuração a partir do seu backend em vez do Dashboard — útil quando você provisiona Merchants programaticamente ou precisa rotacionar segredos periodicamente. Toda entrega que a Tokeflow envia é assinada; sempre verifique a assinatura antes de agir sobre um evento. Veja Verificando assinaturas de webhook.

O segredo de assinatura (whsec_…) é retornado somente quando você cria o endpoint ou rotaciona o segredo. Armazene-o em um gerenciador de segredos nesse momento — ele não pode ser recuperado depois. Rotacionar invalida o segredo anterior, então implante o novo antes de rotacionar, ou aceite uma pequena janela de verificações com falha.

O objeto de endpoint de webhook

Uma configuração de webhook conforme retornada pelos endpoints de criação, listagem e recuperação.

CampoTipoDescrição
idstringIdentificador único da configuração de webhook.
merchant_idstringID do Merchant proprietário desta configuração de webhook.
urlstringA URL para a qual os eventos de webhook serão enviados.
descriptionstring | nullDescrição desta configuração de webhook.
event_filterarray | nullLista de tipos de evento assinados. Null significa todos os eventos.
is_activebooleanSe esta configuração de webhook está ativa.
created_atstringQuando a configuração de webhook foi criada. (ISO 8601 UTC).
updated_atstringQuando a configuração de webhook foi atualizada pela última vez. (ISO 8601 UTC).
last_triggered_atstring | nullQuando o webhook foi disparado pela última vez (entrega mais recente). (ISO 8601 UTC).

Endpoints

GET/api/v1/merchants/:merchant_id/webhook-configs

OrgMerchant

Auth: Chave de Organization (com merchant_id) ou chave de Merchant.

Lista configurações de webhook.

Parâmetros de rota

CampoTipoObrigatórioDescrição
merchant_idstringSim—

Parâmetros de consulta

CampoTipoObrigatórioDescrição
pagenumberNãoNúmero da página (indexado a partir de 1). Padrão 1, mín. 1.
limitnumberNãoNúmero de itens por página. Padrão 20, mín. 1, máx. 100.

Exemplo de requisição

curl -G https://api.tokeflow.com/api/v1/merchants/mrc_8a3f12d9/webhook-configs \
  -H "Authorization: Bearer sk_live_mer_…" \
  --data-urlencode "page=1" \
  --data-urlencode "limit=20"

Exemplo de resposta — 200

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "merchant_id": "550e8400-e29b-41d4-a716-446655440001",
      "url": "https://api.example.com/webhooks/payments",
      "description": "Production payment notifications",
      "event_filter": [
        "transaction.authorized",
        "transaction.failed",
        "transaction.refunded"
      ],
      "is_active": true,
      "created_at": "2024-01-15T10:30:00.000Z",
      "updated_at": "2024-01-15T10:30:00.000Z",
      "last_triggered_at": "2024-01-15T10:30:00.000Z"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 42,
    "total_pages": 3,
    "has_next": true,
    "has_prev": false
  }
}

POST/api/v1/merchants/:merchant_id/webhook-configs

OrgMerchant

Auth: Chave de Organization (com merchant_id) ou chave de Merchant.

Cria uma configuração de webhook.

Parâmetros de rota

CampoTipoObrigatórioDescrição
merchant_idstringSim—

Campos da requisição

CampoTipoObrigatórioDescrição
urlstringSimA URL para a qual os eventos de webhook serão enviados.
descriptionstringNãoDescrição opcional para esta configuração de webhook.
event_filterarrayNãoLista de tipos de evento a assinar. Se não fornecido, todos os eventos serão enviados.

Exemplo de requisição

curl -X POST https://api.tokeflow.com/api/v1/merchants/mrc_8a3f12d9/webhook-configs \
  -H "Authorization: Bearer sk_live_mer_…" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.example.com/webhooks/payments",
    "description": "Production payment notifications",
    "event_filter": [
      "transaction.authorized",
      "transaction.failed",
      "transaction.refunded"
    ]
  }'

Exemplo de resposta — 201

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "merchant_id": "550e8400-e29b-41d4-a716-446655440001",
  "url": "https://api.example.com/webhooks/payments",
  "description": "Production payment notifications",
  "event_filter": [
    "transaction.authorized",
    "transaction.failed",
    "transaction.refunded"
  ],
  "is_active": true,
  "created_at": "2024-01-15T10:30:00.000Z",
  "updated_at": "2024-01-15T10:30:00.000Z",
  "last_triggered_at": "2024-01-15T10:30:00.000Z",
  "secret": "whsec_abc123def456..."
}

DELETE/api/v1/merchants/:merchant_id/webhook-configs/:webhook_id

OrgMerchant

Auth: Chave de Organization (com merchant_id) ou chave de Merchant.

Exclui uma configuração de webhook.

Parâmetros de rota

CampoTipoObrigatórioDescrição
merchant_idstringSim—
webhook_idstringSim—

Exemplo de requisição

curl -X DELETE https://api.tokeflow.com/api/v1/merchants/mrc_8a3f12d9/webhook-configs/whk_3e9d1f42 \
  -H "Authorization: Bearer sk_live_mer_…"

Exemplo de resposta — 204 No Content

Um corpo vazio é retornado em caso de sucesso.

GET/api/v1/merchants/:merchant_id/webhook-configs/:webhook_id

OrgMerchant

Auth: Chave de Organization (com merchant_id) ou chave de Merchant.

Obtém uma configuração de webhook.

Parâmetros de rota

CampoTipoObrigatórioDescrição
merchant_idstringSim—
webhook_idstringSim—

Exemplo de requisição

curl https://api.tokeflow.com/api/v1/merchants/mrc_8a3f12d9/webhook-configs/whk_3e9d1f42 \
  -H "Authorization: Bearer sk_live_mer_…"

Exemplo de resposta — 200

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "merchant_id": "550e8400-e29b-41d4-a716-446655440001",
  "url": "https://api.example.com/webhooks/payments",
  "description": "Production payment notifications",
  "event_filter": [
    "transaction.authorized",
    "transaction.failed",
    "transaction.refunded"
  ],
  "is_active": true,
  "created_at": "2024-01-15T10:30:00.000Z",
  "updated_at": "2024-01-15T10:30:00.000Z",
  "last_triggered_at": "2024-01-15T10:30:00.000Z"
}

PATCH/api/v1/merchants/:merchant_id/webhook-configs/:webhook_id

OrgMerchant

Auth: Chave de Organization (com merchant_id) ou chave de Merchant.

Atualiza uma configuração de webhook.

Parâmetros de rota

CampoTipoObrigatórioDescrição
merchant_idstringSim—
webhook_idstringSim—

Campos da requisição

CampoTipoObrigatórioDescrição
urlstringNãoA URL para a qual os eventos de webhook serão enviados.
descriptionstringNãoDescrição opcional para esta configuração de webhook.
event_filterarrayNãoLista de tipos de evento a assinar.
is_activebooleanNãoSe esta configuração de webhook está ativa.

Exemplo de requisição

curl -X PATCH https://api.tokeflow.com/api/v1/merchants/mrc_8a3f12d9/webhook-configs/whk_3e9d1f42 \
  -H "Authorization: Bearer sk_live_mer_…" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.example.com/webhooks/payments",
    "description": "Production payment notifications",
    "event_filter": [
      "transaction.authorized",
      "transaction.failed",
      "transaction.refunded"
    ],
    "is_active": true
  }'

Exemplo de resposta — 200

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "merchant_id": "550e8400-e29b-41d4-a716-446655440001",
  "url": "https://api.example.com/webhooks/payments",
  "description": "Production payment notifications",
  "event_filter": [
    "transaction.authorized",
    "transaction.failed",
    "transaction.refunded"
  ],
  "is_active": true,
  "created_at": "2024-01-15T10:30:00.000Z",
  "updated_at": "2024-01-15T10:30:00.000Z",
  "last_triggered_at": "2024-01-15T10:30:00.000Z"
}

GET/api/v1/merchants/:merchant_id/webhook-deliveries

OrgMerchant

Auth: Chave de Organization (com merchant_id) ou chave de Merchant.

Lista o histórico de entregas de webhook.

Parâmetros de rota

CampoTipoObrigatórioDescrição
merchant_idstringSim—

Parâmetros de consulta

CampoTipoObrigatórioDescrição
pagenumberNãoNúmero da página (indexado a partir de 1). Padrão 1, mín. 1.
limitnumberNãoNúmero de itens por página. Padrão 20, mín. 1, máx. 100.
statusstringNãoFiltra por status de entrega
fromstringNãoTimestamp inicial (formato ISO 8601) - filtra entregas após esse horário
tostringNãoTimestamp final (formato ISO 8601) - filtra entregas antes desse horário

Exemplo de requisição

curl -G https://api.tokeflow.com/api/v1/merchants/mrc_8a3f12d9/webhook-deliveries \
  -H "Authorization: Bearer sk_live_mer_…" \
  --data-urlencode "page=1" \
  --data-urlencode "limit=20" \
  --data-urlencode "status=failed" \
  --data-urlencode "from=2024-01-01T00:00:00Z"

Exemplo de resposta — 200

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "merchant_id": "550e8400-e29b-41d4-a716-446655440001",
  "merchant_webhook_config_id": "550e8400-e29b-41d4-a716-446655440002",
  "payment_transaction_id": "550e8400-e29b-41d4-a716-446655440003",
  "order_id": "550e8400-e29b-41d4-a716-446655440004",
  "event_type": "transaction.authorized",
  "payload": {
    "event": "transaction.authorized",
    "data": {
      "transaction_id": "..."
    }
  },
  "target_url": "https://api.example.com/webhooks/payments",
  "attempt_number": 1,
  "http_status_code": 200,
  "response_body": "{\"received\": true}",
  "status": "success",
  "next_retry_at": "2024-01-15T10:35:00.000Z",
  "created_at": "2024-01-15T10:30:00.000Z",
  "sent_at": "2024-01-15T10:30:01.000Z"
}

POST/api/v1/merchants/:merchant_id/webhooks/:webhook_id/rotate-secret

OrgMerchant

Auth: Chave de Organization (com merchant_id) ou chave de Merchant.

Rotaciona o segredo do webhook.

Parâmetros de rota

CampoTipoObrigatórioDescrição
merchant_idstringSim—
webhook_idstringSim—

Exemplo de requisição

curl -X POST https://api.tokeflow.com/api/v1/merchants/mrc_8a3f12d9/webhooks/whk_3e9d1f42/rotate-secret \
  -H "Authorization: Bearer sk_live_mer_…"

Exemplo de resposta — 200

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "merchant_id": "550e8400-e29b-41d4-a716-446655440001",
  "url": "https://api.example.com/webhooks/payments",
  "description": "Production payment notifications",
  "event_filter": [
    "transaction.authorized",
    "transaction.failed",
    "transaction.refunded"
  ],
  "is_active": true,
  "created_at": "2024-01-15T10:30:00.000Z",
  "updated_at": "2024-01-15T10:30:00.000Z",
  "last_triggered_at": "2024-01-15T10:30:00.000Z",
  "secret": "whsec_abc123def456..."
}

Erros

Os erros usam o envelope padrão. Os casos mais comuns aqui:

HTTPtypeCausa típica
400validation_errorCampo obrigatório ausente, ou uma operação que o estado atual não permite.
401authentication_errorChave de API ausente ou inválida.
403authorization_errorA chave não tem o escopo necessário.
404not_found_errorO recurso não existe ou não pertence a esta entidade.
429rate_limit_errorLimite de taxa excedido — recue exponencialmente.

Veja Erros para o catálogo completo.

Relacionados

Chaves de API

Anterior

Sessões e tokens

Próxima

Nesta página

O objeto de endpoint de webhookEndpointsGET /api/v1/merchants/:merchant_id/webhook-configsPOST /api/v1/merchants/:merchant_id/webhook-configsDELETE /api/v1/merchants/:merchant_id/webhook-configs/:webhook_idGET /api/v1/merchants/:merchant_id/webhook-configs/:webhook_idPATCH /api/v1/merchants/:merchant_id/webhook-configs/:webhook_idGET /api/v1/merchants/:merchant_id/webhook-deliveriesPOST /api/v1/merchants/:merchant_id/webhooks/:webhook_id/rotate-secretErrosRelacionados