[MARCA] Documentação

Webhooks

Endpoints que recebem os eventos da unidade.

Criar endpoint de webhook

POST /v1/webhook_endpoints

Registra uma URL HTTPS para receber eventos da unidade. O segredo de assinatura (secret) é devolvido somente nesta resposta. Requer o escopo webhooks:manage.

Exige o cabeçalho Idempotency-Key (os SDKs enviam automaticamente).

Corpo da requisição

CampoTipoDescrição
url obrigatóriostring (uri)

Somente HTTPS, porta 443, sem redirecionamentos; endereços privados são recusados.

event_types obrigatórioarray de EventType | string
descriptionstring

Respostas

  • 201 Endpoint criado.
  • 400 Requisição inválida (formato ou campos).
  • 401 Chave ausente, inválida, expirada ou revogada.
  • 403 Operação não permitida: escopo insuficiente (`insufficient-scope`), IP fora da lista permitida
  • 422 Regra de negócio violada: `idempotency-key-reused`, `refund-exceeds-available`,
  • 429 Limite de requisições (`rate-limited`) ou cota diária de cobranças (`quota-exceeded`) excedidos.
  • 500 Erro interno. É seguro repetir com a mesma `Idempotency-Key`.

Exemplo

curl -X POST "https://api.exemplo.com.br/v1/webhook_endpoints" \
  -H "Authorization: Bearer $PIX_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://loja.exemplo.com.br/webhooks/pix",
  "event_types": [
    "charge.paid",
    "refund.succeeded"
  ]
}'

Identificador nos logs: api.webhook_endpoints.create

Listar endpoints de webhook

GET /v1/webhook_endpoints

Requer o escopo webhooks:manage.

Respostas

  • 200 Endpoints da unidade.
  • 401 Chave ausente, inválida, expirada ou revogada.
  • 403 Operação não permitida: escopo insuficiente (`insufficient-scope`), IP fora da lista permitida
  • 429 Limite de requisições (`rate-limited`) ou cota diária de cobranças (`quota-exceeded`) excedidos.
  • 500 Erro interno. É seguro repetir com a mesma `Idempotency-Key`.

Exemplo

curl -X GET "https://api.exemplo.com.br/v1/webhook_endpoints?limit=20" \
  -H "Authorization: Bearer $PIX_API_KEY"

Identificador nos logs: api.webhook_endpoints.list

Consultar endpoint de webhook

GET /v1/webhook_endpoints/{webhook_endpoint_id}

Parâmetros

NomeOndeTipoDescrição
webhook_endpoint_id obrigatóriocaminhostring

Respostas

  • 200 Endpoint.
  • 401 Chave ausente, inválida, expirada ou revogada.
  • 403 Operação não permitida: escopo insuficiente (`insufficient-scope`), IP fora da lista permitida
  • 404 Recurso não encontrado (ou pertencente a outra unidade).
  • 429 Limite de requisições (`rate-limited`) ou cota diária de cobranças (`quota-exceeded`) excedidos.
  • 500 Erro interno. É seguro repetir com a mesma `Idempotency-Key`.

Exemplo

curl -X GET "https://api.exemplo.com.br/v1/webhook_endpoints/we_01J9Z3F0A1B2C3D4E5F6G7H8J9" \
  -H "Authorization: Bearer $PIX_API_KEY"

Identificador nos logs: api.webhook_endpoints.retrieve

Alterar endpoint de webhook

PATCH /v1/webhook_endpoints/{webhook_endpoint_id}

Altera URL, tipos de evento ou status (active/disabled).

Parâmetros

NomeOndeTipoDescrição
webhook_endpoint_id obrigatóriocaminhostring

Corpo da requisição

CampoTipoDescrição
urlstring (uri)
event_typesarray de EventType | string
descriptionstring
statusstring
activedisabled

Respostas

  • 200 Endpoint alterado.
  • 400 Requisição inválida (formato ou campos).
  • 401 Chave ausente, inválida, expirada ou revogada.
  • 403 Operação não permitida: escopo insuficiente (`insufficient-scope`), IP fora da lista permitida
  • 404 Recurso não encontrado (ou pertencente a outra unidade).
  • 422 Regra de negócio violada: `idempotency-key-reused`, `refund-exceeds-available`,
  • 429 Limite de requisições (`rate-limited`) ou cota diária de cobranças (`quota-exceeded`) excedidos.
  • 500 Erro interno. É seguro repetir com a mesma `Idempotency-Key`.

Exemplo

curl -X PATCH "https://api.exemplo.com.br/v1/webhook_endpoints/we_01J9Z3F0A1B2C3D4E5F6G7H8J9" \
  -H "Authorization: Bearer $PIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "event_types": [
    "*"
  ]
}'

Identificador nos logs: api.webhook_endpoints.update

Remover endpoint de webhook

DELETE /v1/webhook_endpoints/{webhook_endpoint_id}

Parâmetros

NomeOndeTipoDescrição
webhook_endpoint_id obrigatóriocaminhostring

Respostas

  • 204 Endpoint removido. Entregas pendentes são canceladas.
  • 401 Chave ausente, inválida, expirada ou revogada.
  • 403 Operação não permitida: escopo insuficiente (`insufficient-scope`), IP fora da lista permitida
  • 404 Recurso não encontrado (ou pertencente a outra unidade).
  • 429 Limite de requisições (`rate-limited`) ou cota diária de cobranças (`quota-exceeded`) excedidos.
  • 500 Erro interno. É seguro repetir com a mesma `Idempotency-Key`.

Exemplo

curl -X DELETE "https://api.exemplo.com.br/v1/webhook_endpoints/we_01J9Z3F0A1B2C3D4E5F6G7H8J9" \
  -H "Authorization: Bearer $PIX_API_KEY"

Identificador nos logs: api.webhook_endpoints.delete

Rotacionar segredo de assinatura

POST /v1/webhook_endpoints/{webhook_endpoint_id}/rotate_secret

Gera um novo segredo. Durante 24 horas os eventos são assinados com o segredo novo e o anterior (duas assinaturas no cabeçalho webhook-signature), para permitir a troca sem perda de eventos.

Exige o cabeçalho Idempotency-Key (os SDKs enviam automaticamente).

Parâmetros

NomeOndeTipoDescrição
webhook_endpoint_id obrigatóriocaminhostring

Respostas

  • 200 Novo segredo (exibido somente nesta resposta).
  • 401 Chave ausente, inválida, expirada ou revogada.
  • 403 Operação não permitida: escopo insuficiente (`insufficient-scope`), IP fora da lista permitida
  • 404 Recurso não encontrado (ou pertencente a outra unidade).
  • 429 Limite de requisições (`rate-limited`) ou cota diária de cobranças (`quota-exceeded`) excedidos.
  • 500 Erro interno. É seguro repetir com a mesma `Idempotency-Key`.

Exemplo

curl -X POST "https://api.exemplo.com.br/v1/webhook_endpoints/we_01J9Z3F0A1B2C3D4E5F6G7H8J9/rotate_secret" \
  -H "Authorization: Bearer $PIX_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

Identificador nos logs: api.webhook_endpoints.rotate_secret

Enviar evento de teste

POST /v1/webhook_endpoints/{webhook_endpoint_id}/test

Envia um evento ping assinado para o endpoint e devolve o resultado da entrega.

Exige o cabeçalho Idempotency-Key (os SDKs enviam automaticamente).

Parâmetros

NomeOndeTipoDescrição
webhook_endpoint_id obrigatóriocaminhostring

Respostas

  • 200 Resultado da entrega de teste.
  • 401 Chave ausente, inválida, expirada ou revogada.
  • 403 Operação não permitida: escopo insuficiente (`insufficient-scope`), IP fora da lista permitida
  • 404 Recurso não encontrado (ou pertencente a outra unidade).
  • 429 Limite de requisições (`rate-limited`) ou cota diária de cobranças (`quota-exceeded`) excedidos.
  • 500 Erro interno. É seguro repetir com a mesma `Idempotency-Key`.

Exemplo

curl -X POST "https://api.exemplo.com.br/v1/webhook_endpoints/we_01J9Z3F0A1B2C3D4E5F6G7H8J9/test" \
  -H "Authorization: Bearer $PIX_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

Identificador nos logs: api.webhook_endpoints.test