tokeflow.com
DocumentaçãoReferência da APIDashboardsSDKsChangelog

Webhooks da Organization

Gerencie endpoints de webhook em toda a Organization a partir do Dashboard — configs, entregas e rotação de segredos.

Esses endpoints sustentam a tela de webhooks da Organization: registrar endpoints, inspecionar entregas e novas tentativas, e rotacionar segredos de assinatura, em todos os Merchants da Organization.

O segredo de assinatura (whsec_…) é exibido apenas quando criado ou rotacionado — capture-o nesse momento. Toda entrega é assinada; verifique o X-Tokeflow-Signature antes de agir. Consulte Verificando assinaturas.

Esses endpoints alimentam a interface do Tokeflow Dashboard no nível da Organization. Eles são autenticados por sessão (JWT bearer) — o token vem do login no Dashboard, não de uma chave de API sk_/pk_. As solicitações também carregam o header x-organization-id, e o usuário autenticado deve ser membro dessa Organization.

O objeto de configuração de webhook

Retornado pelos endpoints de listagem e de recuperação desta página.

CampoTipoDescrição
idstringIdentificador único da configuração de webhook.
merchant_idstringID do Merchant que possui esta configuração de webhook.
urlstringA URL para onde 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 acionado pela última vez (entrega mais recente). (ISO 8601 UTC).

Endpoints

GET/api/v1/org/webhooks

Org

Auth: Dashboard session (JWT bearer). É necessário ser membro da Organization.

Lista as configurações de webhook do Merchant.

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 solicitação

curl -G https://api.tokeflow.com/api/v1/org/webhooks \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-organization-id: org_4b21e7c3" \
  --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/org/webhooks

Org

Auth: Dashboard session (JWT bearer). É necessário ser membro da Organization.

Cria uma nova configuração de webhook.

Campos da solicitação

CampoTipoObrigatórioDescrição
urlstringSimA URL para onde 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 for fornecida, todos os eventos serão enviados.

Exemplo de solicitação

curl -X POST https://api.tokeflow.com/api/v1/org/webhooks \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-organization-id: org_4b21e7c3" \
  -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..."
}

GET/api/v1/org/webhooks/deliveries

Org

Auth: Dashboard session (JWT bearer). É necessário ser membro da Organization.

Lista todas as entregas de webhook do Merchant.

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.
statusstringSim—

Exemplo de solicitação

curl -G https://api.tokeflow.com/api/v1/org/webhooks/deliveries \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-organization-id: org_4b21e7c3" \
  --data-urlencode "page=1" \
  --data-urlencode "limit=20" \
  --data-urlencode "status=active"

Exemplo de resposta — 200

{
  "data": [
    {
      "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"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 42,
    "total_pages": 3,
    "has_next": true,
    "has_prev": false
  }
}

GET/api/v1/org/webhooks/webhook-deliveries/:delivery_id

Org

Auth: Dashboard session (JWT bearer). É necessário ser membro da Organization.

Obtém uma entrega de webhook específica.

Parâmetros de caminho

CampoTipoObrigatórioDescrição
delivery_idstringSim—

Exemplo de solicitação

curl https://api.tokeflow.com/api/v1/org/webhooks/webhook-deliveries/123 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-organization-id: org_4b21e7c3"

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"
}

DELETE/api/v1/org/webhooks/:webhook_id

Org

Auth: Dashboard session (JWT bearer). É necessário ser membro da Organization.

Exclui uma configuração de webhook.

Parâmetros de caminho

CampoTipoObrigatórioDescrição
webhook_idstringSim—

Exemplo de solicitação

curl -X DELETE https://api.tokeflow.com/api/v1/org/webhooks/whk_3e9d1f42 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-organization-id: org_4b21e7c3"

Exemplo de resposta — 204 No Content

Um corpo vazio é retornado em caso de sucesso.

GET/api/v1/org/webhooks/:webhook_id

Org

Auth: Dashboard session (JWT bearer). É necessário ser membro da Organization.

Obtém a configuração de webhook por ID.

Parâmetros de caminho

CampoTipoObrigatórioDescrição
webhook_idstringSim—

Exemplo de solicitação

curl https://api.tokeflow.com/api/v1/org/webhooks/whk_3e9d1f42 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-organization-id: org_4b21e7c3"

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/org/webhooks/:webhook_id

Org

Auth: Dashboard session (JWT bearer). É necessário ser membro da Organization.

Atualiza uma configuração de webhook.

Parâmetros de caminho

CampoTipoObrigatórioDescrição
webhook_idstringSim—

Campos da solicitação

CampoTipoObrigatórioDescrição
urlstringNãoA URL para onde 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 solicitação

curl -X PATCH https://api.tokeflow.com/api/v1/org/webhooks/whk_3e9d1f42 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-organization-id: org_4b21e7c3" \
  -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/org/webhooks/:webhook_id/deliveries

Org

Auth: Dashboard session (JWT bearer). É necessário ser membro da Organization.

Lista as entregas de webhook de um webhook específico.

Parâmetros de caminho

CampoTipoObrigatórioDescrição
webhook_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 pelo status da entrega
fromstringNãoTimestamp inicial (formato ISO 8601) - filtra entregas após este horário
tostringNãoTimestamp final (formato ISO 8601) - filtra entregas antes deste horário

Exemplo de solicitação

curl -G https://api.tokeflow.com/api/v1/org/webhooks/whk_3e9d1f42/deliveries \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-organization-id: org_4b21e7c3" \
  --data-urlencode "page=1" \
  --data-urlencode "limit=20" \
  --data-urlencode "status=failed" \
  --data-urlencode "from=2024-01-01T00:00:00Z"

Exemplo de resposta — 200

{
  "data": [
    {
      "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"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 42,
    "total_pages": 3,
    "has_next": true,
    "has_prev": false
  }
}

POST/api/v1/org/webhooks/:webhook_id/rotate-secret

Org

Auth: Dashboard session (JWT bearer). É necessário ser membro da Organization.

Rotaciona o segredo do webhook.

Parâmetros de caminho

CampoTipoObrigatórioDescrição
webhook_idstringSim—

Exemplo de solicitação

curl -X POST https://api.tokeflow.com/api/v1/org/webhooks/whk_3e9d1f42/rotate-secret \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-organization-id: org_4b21e7c3"

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..."
}

POST/api/v1/org/webhooks/:webhook_id/test

Org

Auth: Dashboard session (JWT bearer). É necessário ser membro da Organization.

Testa uma configuração de webhook enviando um evento de teste.

Parâmetros de caminho

CampoTipoObrigatórioDescrição
webhook_idstringSim—

Exemplo de solicitação

curl -X POST https://api.tokeflow.com/api/v1/org/webhooks/whk_3e9d1f42/test \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-organization-id: org_4b21e7c3"

Exemplo de resposta — 200

{
  "success": true,
  "message": "Operation completed successfully",
  "http_status": 200
}

Erros

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

HTTPSignificado
400Parâmetros inválidos ou um estado que não permite esta operação.
401Token de sessão do Dashboard ausente, expirado ou inválido.
403Autenticado, mas o usuário autenticado não tem acesso a esta entidade.
404O registro não existe ou não é visível para esta entidade.

Relacionados

Transações da Organization

Anterior

Sessões e configuração do Customer Portal

Próxima

Nesta página

O objeto de configuração de webhookEndpointsGET /api/v1/org/webhooksPOST /api/v1/org/webhooksGET /api/v1/org/webhooks/deliveriesGET /api/v1/org/webhooks/webhook-deliveries/:delivery_idDELETE /api/v1/org/webhooks/:webhook_idGET /api/v1/org/webhooks/:webhook_idPATCH /api/v1/org/webhooks/:webhook_idGET /api/v1/org/webhooks/:webhook_id/deliveriesPOST /api/v1/org/webhooks/:webhook_id/rotate-secretPOST /api/v1/org/webhooks/:webhook_id/testErrosRelacionados