Referência da API

Webhooks

Endpoints, entregas assinadas, retentativas e reenvio.

Cadastrar endpoint de webhook

POST/v1/webhook-endpointsImplementada

Chave de API (Authorization: Bearer ep_…)· escopo webhooks:write· createWebhookEndpoint

Cadastra um destino para receber eventos assinados (até 10 por conta). O segredo whsec_… aparece só nesta resposta; ele é guardado cifrado e assina cada entrega. Repetir a criação com a mesma Idempotency-Key devolve o endpoint sem o segredo. HTTPS é obrigatório em produção; endereços internos, privados, de loopback ou de metadata são recusados aqui e de novo em cada entrega, depois da resolução de DNS.

Escopo da chave: webhooks:write.

Idempotência: exige o header Idempotency-Key.

Headers de createWebhookEndpoint
Header	Obrigatório	Descrição
`X-Account-Id`	sim	Conta permitida pelos grants do principal.
`Idempotency-Key`	sim	Chave única por intenção (16 a 128 caracteres visíveis). Ao refazer a mesma chamada, repita a mesma chave: o resultado gravado é devolvido. Mesma chave com outro conteúdo responde 409 IDEMPOTENCY_CONFLICT.

Parâmetros de createWebhookEndpoint
Parâmetro	Onde	Tipo	Descrição
`Eclipta-Pay-Version`	header	"2026-11-13"	Versão de data do contrato. Opcional; a resposta sempre informa a versão usada. Valor desconhecido responde 400 UNSUPPORTED_API_VERSION.

Corpo da requisição

Campos do corpo de createWebhookEndpoint
Campo	Tipo	Descrição
`url` obrigatório	texto	URL de destino. HTTPS obrigatório em produção; `http://` só no ambiente de testes. Endereços internos, privados, de loopback e de metadata são recusados. 0–2048 caracteres
`events` obrigatório	lista de SubscribableEventType	Tipos do catálogo que este endpoint recebe; `["*"]` recebe todos. 1–50 itens
`description`	texto	Rótulo livre para identificar o endpoint no painel. 1–200 caracteres

Exemplo

curl -X POST "$ECLIPTA_PAY_API/v1/webhook-endpoints" \
  -H "Authorization: Bearer $ECLIPTA_PAY_KEY" \
  -H "X-Account-Id: $ECLIPTA_PAY_ACCOUNT" \
  -H "Idempotency-Key: <uma chave por intenção>" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://loja.exemplo.com.br/webhooks/eclipta","events":["payment.confirmed","order.payment_completed"],"description":"Produção da loja"}'

Resposta 201: Recurso criado.

Campos da resposta 201 de createWebhookEndpoint
Campo	Tipo	Descrição
`id` obrigatório	Id (texto)	8–160 caracteres · formato ^[A-Za-z0-9_]+$
`url` obrigatório	texto
`description` obrigatório	texto ou nulo
`events` obrigatório	lista de texto
`status` obrigatório	"ACTIVE" \| "DISABLED" \| "AUTO_DISABLED"	ACTIVE recebe; DISABLED foi pausado pelo integrador; AUTO_DISABLED foi desativado após 3 dias seguidos de falhas.
`apiVersion` obrigatório	"2026-11-13"
`secretVersion` obrigatório	inteiro	Versão do segredo atual; é o valor do header Eclipta-Pay-Key-Id. 1 a 9007199254740991
`previousSecretVersion` obrigatório	inteiro ou nulo
`previousSecretExpiresAt` obrigatório	data e hora (ISO 8601) ou nulo	Até quando o segredo anterior ainda assina (rotação com sobreposição).
`consecutiveFailures` obrigatório	inteiro	0 a 9007199254740991
`failingSince` obrigatório	data e hora (ISO 8601) ou nulo
`lastSuccessAt` obrigatório	data e hora (ISO 8601) ou nulo
`lastFailureAt` obrigatório	data e hora (ISO 8601) ou nulo
`disabledAt` obrigatório	data e hora (ISO 8601) ou nulo
`disabledReason` obrigatório	"MANUAL" \| "CONSECUTIVE_FAILURES" ou nulo
`createdAt` obrigatório	data e hora (ISO 8601)	formato ^(?:(?:\d\d[2468][048]\|\d\d[13579][26]\|\d\d0[48]\|[02468][048]00\|[13579][26]00)-02-29\|\d{4}-(?:(?:0[13578]\|1[02])-(?:0[1-9]\|[12]\d\|3[01])\|(?:0[469]\|11)-(?:0[1-9]\|[12]\d\|30)\|(?:02)-(?:0[1-9]\|1\d\|2[0-8])))T(?:(?:[01]\d\|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z\|([+-](?:[01]\d\|2[0-3]):[0-5]\d)))$
`updatedAt` obrigatório	data e hora (ISO 8601)	formato ^(?:(?:\d\d[2468][048]\|\d\d[13579][26]\|\d\d0[48]\|[02468][048]00\|[13579][26]00)-02-29\|\d{4}-(?:(?:0[13578]\|1[02])-(?:0[1-9]\|[12]\d\|3[01])\|(?:0[469]\|11)-(?:0[1-9]\|[12]\d\|30)\|(?:02)-(?:0[1-9]\|1\d\|2[0-8])))T(?:(?:[01]\d\|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z\|([+-](?:[01]\d\|2[0-3]):[0-5]\d)))$
`secret`	texto	Segredo de assinatura. Exibido só na resposta da criação e da rotação; guarde-o com segurança. formato ^whsec_.*

Exemplo 201

{
  "id": "whk_01JDY9A1B2C3D4E5F6G7H8J9KF",
  "url": "https://loja.exemplo.com.br/webhooks/eclipta",
  "description": "Produção da loja",
  "events": [
    "payment.confirmed",
    "order.payment_completed"
  ],
  "status": "ACTIVE",
  "apiVersion": "2026-11-13",
  "secretVersion": 1,
  "previousSecretVersion": null,
  "previousSecretExpiresAt": null,
  "consecutiveFailures": 0,
  "failingSince": null,
  "lastSuccessAt": null,
  "lastFailureAt": null,
  "disabledAt": null,
  "disabledReason": null,
  "createdAt": "2026-11-13T13:00:00.000Z",
  "updatedAt": "2026-11-13T13:00:00.000Z",
  "secret": "whsec_Exemplo3xAm9lE0nLy7cT2vK4pQ8wZ1sB6dF5gH0jL"
}

Erros

Erros de createWebhookEndpoint
HTTP	Exemplo de code	Quando
400	`INVALID_REQUEST`	Requisição inválida: fieldErrors aponta cada campo.
401	`INVALID_API_KEY`	Chave de API ausente, inválida, expirada ou revogada.
403	`SCOPE_MISSING`	Escopo ausente, conta não permitida em X-Account-Id, IP fora da lista ou conta suspensa.
409	`IDEMPOTENCY_CONFLICT`	Conflito de idempotência (IDEMPOTENCY_CONFLICT), requisição em andamento com a mesma chave (REQUEST_IN_PROGRESS) ou estado do recurso.
422	`CAPABILITY_UNAVAILABLE`	Regra de negócio ou capacidade indisponível para a conta.
429	`TOO_MANY_REQUESTS`	Limite de requisições da chave atingido (rajada de 100 e 6.000 por minuto). Toda resposta traz RateLimit-Limit, RateLimit-Remaining e RateLimit-Reset; o 429 traz Retry-After em segundos. Aguarde e repita com a mesma Idempotency-Key.

Listar endpoints de webhook

GET/v1/webhook-endpointsImplementada

Chave de API (Authorization: Bearer ep_…)· escopo webhooks:write· listWebhookEndpoints

Lista os endpoints da conta (sem segredos), com filtro opcional por situação.

Escopo da chave: webhooks:write.

Headers de listWebhookEndpoints
Header	Obrigatório	Descrição
`X-Account-Id`	sim	Conta permitida pelos grants do principal.

Parâmetros de listWebhookEndpoints
Parâmetro	Onde	Tipo	Descrição
`cursor`	query	texto	0–200 caracteres
`limit`	query	inteiro	1 a 100 · padrão 20
`status`	query	"ACTIVE" \| "DISABLED" \| "AUTO_DISABLED"
`Eclipta-Pay-Version`	header	"2026-11-13"	Versão de data do contrato. Opcional; a resposta sempre informa a versão usada. Valor desconhecido responde 400 UNSUPPORTED_API_VERSION.

Exemplo

curl -X GET "$ECLIPTA_PAY_API/v1/webhook-endpoints" \
  -H "Authorization: Bearer $ECLIPTA_PAY_KEY" \
  -H "X-Account-Id: $ECLIPTA_PAY_ACCOUNT"

Resposta 200: Sucesso.

Campos da resposta 200 de listWebhookEndpoints
Campo	Tipo	Descrição
`data` obrigatório	lista de WebhookEndpoint
`data[].id` obrigatório	Id (texto)	8–160 caracteres · formato ^[A-Za-z0-9_]+$
`data[].url` obrigatório	texto
`data[].description` obrigatório	texto ou nulo
`data[].events` obrigatório	lista de texto
`data[].status` obrigatório	"ACTIVE" \| "DISABLED" \| "AUTO_DISABLED"	ACTIVE recebe; DISABLED foi pausado pelo integrador; AUTO_DISABLED foi desativado após 3 dias seguidos de falhas.
`data[].apiVersion` obrigatório	"2026-11-13"
`data[].secretVersion` obrigatório	inteiro	Versão do segredo atual; é o valor do header Eclipta-Pay-Key-Id. 1 a 9007199254740991
`data[].previousSecretVersion` obrigatório	inteiro ou nulo
`data[].previousSecretExpiresAt` obrigatório	data e hora (ISO 8601) ou nulo	Até quando o segredo anterior ainda assina (rotação com sobreposição).
`data[].consecutiveFailures` obrigatório	inteiro	0 a 9007199254740991
`data[].failingSince` obrigatório	data e hora (ISO 8601) ou nulo
`data[].lastSuccessAt` obrigatório	data e hora (ISO 8601) ou nulo
`data[].lastFailureAt` obrigatório	data e hora (ISO 8601) ou nulo
`data[].disabledAt` obrigatório	data e hora (ISO 8601) ou nulo
`data[].disabledReason` obrigatório	"MANUAL" \| "CONSECUTIVE_FAILURES" ou nulo
`data[].createdAt` obrigatório	data e hora (ISO 8601)	formato ^(?:(?:\d\d[2468][048]\|\d\d[13579][26]\|\d\d0[48]\|[02468][048]00\|[13579][26]00)-02-29\|\d{4}-(?:(?:0[13578]\|1[02])-(?:0[1-9]\|[12]\d\|3[01])\|(?:0[469]\|11)-(?:0[1-9]\|[12]\d\|30)\|(?:02)-(?:0[1-9]\|1\d\|2[0-8])))T(?:(?:[01]\d\|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z\|([+-](?:[01]\d\|2[0-3]):[0-5]\d)))$
`data[].updatedAt` obrigatório	data e hora (ISO 8601)	formato ^(?:(?:\d\d[2468][048]\|\d\d[13579][26]\|\d\d0[48]\|[02468][048]00\|[13579][26]00)-02-29\|\d{4}-(?:(?:0[13578]\|1[02])-(?:0[1-9]\|[12]\d\|3[01])\|(?:0[469]\|11)-(?:0[1-9]\|[12]\d\|30)\|(?:02)-(?:0[1-9]\|1\d\|2[0-8])))T(?:(?:[01]\d\|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z\|([+-](?:[01]\d\|2[0-3]):[0-5]\d)))$
`data[].secret`	texto	Segredo de assinatura. Exibido só na resposta da criação e da rotação; guarde-o com segurança. formato ^whsec_.*
`nextCursor` obrigatório	texto ou nulo

Exemplo 200

{
  "data": [
    {
      "id": "whk_01JDY9A1B2C3D4E5F6G7H8J9KF",
      "url": "https://loja.exemplo.com.br/webhooks/eclipta",
      "description": "Produção da loja",
      "events": [
        "payment.confirmed",
        "order.payment_completed"
      ],
      "status": "ACTIVE",
      "apiVersion": "2026-11-13",
      "secretVersion": 1,
      "previousSecretVersion": null,
      "previousSecretExpiresAt": null,
      "consecutiveFailures": 0,
      "failingSince": null,
      "lastSuccessAt": null,
      "lastFailureAt": null,
      "disabledAt": null,
      "disabledReason": null,
      "createdAt": "2026-11-13T13:00:00.000Z",
      "updatedAt": "2026-11-13T13:00:00.000Z"
    }
  ],
  "nextCursor": null
}

Erros

Erros de listWebhookEndpoints
HTTP	Exemplo de code	Quando
400	`INVALID_REQUEST`	Requisição inválida: fieldErrors aponta cada campo.
401	`INVALID_API_KEY`	Chave de API ausente, inválida, expirada ou revogada.
403	`SCOPE_MISSING`	Escopo ausente, conta não permitida em X-Account-Id, IP fora da lista ou conta suspensa.
429	`TOO_MANY_REQUESTS`	Limite de requisições da chave atingido (rajada de 100 e 6.000 por minuto). Toda resposta traz RateLimit-Limit, RateLimit-Remaining e RateLimit-Reset; o 429 traz Retry-After em segundos. Aguarde e repita com a mesma Idempotency-Key.

Consultar endpoint de webhook

GET/v1/webhook-endpoints/{id}Implementada

Chave de API (Authorization: Bearer ep_…)· escopo webhooks:write· getWebhookEndpoint

Consulta um endpoint, sua saúde (falhas seguidas, último sucesso) e a versão do segredo. O segredo nunca é devolvido aqui.

Escopo da chave: webhooks:write.

Headers de getWebhookEndpoint
Header	Obrigatório	Descrição
`X-Account-Id`	sim	Conta permitida pelos grants do principal.

Parâmetros de getWebhookEndpoint
Parâmetro	Onde	Tipo	Descrição
`id` obrigatório	caminho	Id (texto)	8–160 caracteres · formato ^[A-Za-z0-9_]+$
`Eclipta-Pay-Version`	header	"2026-11-13"	Versão de data do contrato. Opcional; a resposta sempre informa a versão usada. Valor desconhecido responde 400 UNSUPPORTED_API_VERSION.

Exemplo

curl -X GET "$ECLIPTA_PAY_API/v1/webhook-endpoints/{id}" \
  -H "Authorization: Bearer $ECLIPTA_PAY_KEY" \
  -H "X-Account-Id: $ECLIPTA_PAY_ACCOUNT"

Resposta 200: Sucesso.

Campos da resposta 200 de getWebhookEndpoint
Campo	Tipo	Descrição
`id` obrigatório	Id (texto)	8–160 caracteres · formato ^[A-Za-z0-9_]+$
`url` obrigatório	texto
`description` obrigatório	texto ou nulo
`events` obrigatório	lista de texto
`status` obrigatório	"ACTIVE" \| "DISABLED" \| "AUTO_DISABLED"	ACTIVE recebe; DISABLED foi pausado pelo integrador; AUTO_DISABLED foi desativado após 3 dias seguidos de falhas.
`apiVersion` obrigatório	"2026-11-13"
`secretVersion` obrigatório	inteiro	Versão do segredo atual; é o valor do header Eclipta-Pay-Key-Id. 1 a 9007199254740991
`previousSecretVersion` obrigatório	inteiro ou nulo
`previousSecretExpiresAt` obrigatório	data e hora (ISO 8601) ou nulo	Até quando o segredo anterior ainda assina (rotação com sobreposição).
`consecutiveFailures` obrigatório	inteiro	0 a 9007199254740991
`failingSince` obrigatório	data e hora (ISO 8601) ou nulo
`lastSuccessAt` obrigatório	data e hora (ISO 8601) ou nulo
`lastFailureAt` obrigatório	data e hora (ISO 8601) ou nulo
`disabledAt` obrigatório	data e hora (ISO 8601) ou nulo
`disabledReason` obrigatório	"MANUAL" \| "CONSECUTIVE_FAILURES" ou nulo
`createdAt` obrigatório	data e hora (ISO 8601)	formato ^(?:(?:\d\d[2468][048]\|\d\d[13579][26]\|\d\d0[48]\|[02468][048]00\|[13579][26]00)-02-29\|\d{4}-(?:(?:0[13578]\|1[02])-(?:0[1-9]\|[12]\d\|3[01])\|(?:0[469]\|11)-(?:0[1-9]\|[12]\d\|30)\|(?:02)-(?:0[1-9]\|1\d\|2[0-8])))T(?:(?:[01]\d\|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z\|([+-](?:[01]\d\|2[0-3]):[0-5]\d)))$
`updatedAt` obrigatório	data e hora (ISO 8601)	formato ^(?:(?:\d\d[2468][048]\|\d\d[13579][26]\|\d\d0[48]\|[02468][048]00\|[13579][26]00)-02-29\|\d{4}-(?:(?:0[13578]\|1[02])-(?:0[1-9]\|[12]\d\|3[01])\|(?:0[469]\|11)-(?:0[1-9]\|[12]\d\|30)\|(?:02)-(?:0[1-9]\|1\d\|2[0-8])))T(?:(?:[01]\d\|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z\|([+-](?:[01]\d\|2[0-3]):[0-5]\d)))$
`secret`	texto	Segredo de assinatura. Exibido só na resposta da criação e da rotação; guarde-o com segurança. formato ^whsec_.*

Exemplo 200

{
  "id": "whk_01JDY9A1B2C3D4E5F6G7H8J9KF",
  "url": "https://loja.exemplo.com.br/webhooks/eclipta",
  "description": "Produção da loja",
  "events": [
    "payment.confirmed",
    "order.payment_completed"
  ],
  "status": "ACTIVE",
  "apiVersion": "2026-11-13",
  "secretVersion": 1,
  "previousSecretVersion": null,
  "previousSecretExpiresAt": null,
  "consecutiveFailures": 0,
  "failingSince": null,
  "lastSuccessAt": null,
  "lastFailureAt": null,
  "disabledAt": null,
  "disabledReason": null,
  "createdAt": "2026-11-13T13:00:00.000Z",
  "updatedAt": "2026-11-13T13:00:00.000Z"
}

Erros

Erros de getWebhookEndpoint
HTTP	Exemplo de code	Quando
400	`INVALID_REQUEST`	Requisição inválida: fieldErrors aponta cada campo.
401	`INVALID_API_KEY`	Chave de API ausente, inválida, expirada ou revogada.
403	`SCOPE_MISSING`	Escopo ausente, conta não permitida em X-Account-Id, IP fora da lista ou conta suspensa.
404	`RESOURCE_NOT_FOUND`	Recurso inexistente nesta conta (inclusive recurso de outra conta ou de outro tenant).
429	`TOO_MANY_REQUESTS`	Limite de requisições da chave atingido (rajada de 100 e 6.000 por minuto). Toda resposta traz RateLimit-Limit, RateLimit-Remaining e RateLimit-Reset; o 429 traz Retry-After em segundos. Aguarde e repita com a mesma Idempotency-Key.

Atualizar, pausar ou reativar endpoint

PATCH/v1/webhook-endpoints/{id}Implementada

Chave de API (Authorization: Bearer ep_…)· escopo webhooks:write· updateWebhookEndpoint

Altera URL, tipos ou rótulo. enabled: false pausa as entregas; enabled: true reativa o endpoint, inclusive depois da desativação automática, zera o contador de falhas e retoma as entregas pendentes. A ação fica na trilha de auditoria.

Escopo da chave: webhooks:write.

Idempotência: exige o header Idempotency-Key.

Headers de updateWebhookEndpoint
Header	Obrigatório	Descrição
`X-Account-Id`	sim	Conta permitida pelos grants do principal.
`Idempotency-Key`	sim	Chave única por intenção (16 a 128 caracteres visíveis). Ao refazer a mesma chamada, repita a mesma chave: o resultado gravado é devolvido. Mesma chave com outro conteúdo responde 409 IDEMPOTENCY_CONFLICT.

Parâmetros de updateWebhookEndpoint
Parâmetro	Onde	Tipo	Descrição
`id` obrigatório	caminho	Id (texto)	8–160 caracteres · formato ^[A-Za-z0-9_]+$
`Eclipta-Pay-Version`	header	"2026-11-13"	Versão de data do contrato. Opcional; a resposta sempre informa a versão usada. Valor desconhecido responde 400 UNSUPPORTED_API_VERSION.

Corpo da requisição

Campos do corpo de updateWebhookEndpoint
Campo	Tipo	Descrição
`url`	texto	URL de destino. HTTPS obrigatório em produção; `http://` só no ambiente de testes. Endereços internos, privados, de loopback e de metadata são recusados. 0–2048 caracteres
`events`	lista de SubscribableEventType	Tipos do catálogo que este endpoint recebe; `["*"]` recebe todos. 1–50 itens
`description`	texto ou nulo
`enabled`	booleano	`false` pausa as entregas; `true` reativa (inclusive após desativação automática) e retoma as entregas pendentes.

Exemplo

curl -X PATCH "$ECLIPTA_PAY_API/v1/webhook-endpoints/{id}" \
  -H "Authorization: Bearer $ECLIPTA_PAY_KEY" \
  -H "X-Account-Id: $ECLIPTA_PAY_ACCOUNT" \
  -H "Idempotency-Key: <uma chave por intenção>" \
  -H "Content-Type: application/json" \
  -d '{"enabled":true}'

Resposta 200: Sucesso.

Campos da resposta 200 de updateWebhookEndpoint
Campo	Tipo	Descrição
`id` obrigatório	Id (texto)	8–160 caracteres · formato ^[A-Za-z0-9_]+$
`url` obrigatório	texto
`description` obrigatório	texto ou nulo
`events` obrigatório	lista de texto
`status` obrigatório	"ACTIVE" \| "DISABLED" \| "AUTO_DISABLED"	ACTIVE recebe; DISABLED foi pausado pelo integrador; AUTO_DISABLED foi desativado após 3 dias seguidos de falhas.
`apiVersion` obrigatório	"2026-11-13"
`secretVersion` obrigatório	inteiro	Versão do segredo atual; é o valor do header Eclipta-Pay-Key-Id. 1 a 9007199254740991
`previousSecretVersion` obrigatório	inteiro ou nulo
`previousSecretExpiresAt` obrigatório	data e hora (ISO 8601) ou nulo	Até quando o segredo anterior ainda assina (rotação com sobreposição).
`consecutiveFailures` obrigatório	inteiro	0 a 9007199254740991
`failingSince` obrigatório	data e hora (ISO 8601) ou nulo
`lastSuccessAt` obrigatório	data e hora (ISO 8601) ou nulo
`lastFailureAt` obrigatório	data e hora (ISO 8601) ou nulo
`disabledAt` obrigatório	data e hora (ISO 8601) ou nulo
`disabledReason` obrigatório	"MANUAL" \| "CONSECUTIVE_FAILURES" ou nulo
`createdAt` obrigatório	data e hora (ISO 8601)	formato ^(?:(?:\d\d[2468][048]\|\d\d[13579][26]\|\d\d0[48]\|[02468][048]00\|[13579][26]00)-02-29\|\d{4}-(?:(?:0[13578]\|1[02])-(?:0[1-9]\|[12]\d\|3[01])\|(?:0[469]\|11)-(?:0[1-9]\|[12]\d\|30)\|(?:02)-(?:0[1-9]\|1\d\|2[0-8])))T(?:(?:[01]\d\|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z\|([+-](?:[01]\d\|2[0-3]):[0-5]\d)))$
`updatedAt` obrigatório	data e hora (ISO 8601)	formato ^(?:(?:\d\d[2468][048]\|\d\d[13579][26]\|\d\d0[48]\|[02468][048]00\|[13579][26]00)-02-29\|\d{4}-(?:(?:0[13578]\|1[02])-(?:0[1-9]\|[12]\d\|3[01])\|(?:0[469]\|11)-(?:0[1-9]\|[12]\d\|30)\|(?:02)-(?:0[1-9]\|1\d\|2[0-8])))T(?:(?:[01]\d\|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z\|([+-](?:[01]\d\|2[0-3]):[0-5]\d)))$
`secret`	texto	Segredo de assinatura. Exibido só na resposta da criação e da rotação; guarde-o com segurança. formato ^whsec_.*

Exemplo 200

{
  "id": "whk_01JDY9A1B2C3D4E5F6G7H8J9KF",
  "url": "https://loja.exemplo.com.br/webhooks/eclipta",
  "description": "Produção da loja",
  "events": [
    "payment.confirmed",
    "order.payment_completed"
  ],
  "status": "ACTIVE",
  "apiVersion": "2026-11-13",
  "secretVersion": 1,
  "previousSecretVersion": null,
  "previousSecretExpiresAt": null,
  "consecutiveFailures": 0,
  "failingSince": null,
  "lastSuccessAt": null,
  "lastFailureAt": null,
  "disabledAt": null,
  "disabledReason": null,
  "createdAt": "2026-11-13T13:00:00.000Z",
  "updatedAt": "2026-11-13T13:00:00.000Z"
}

Erros

Erros de updateWebhookEndpoint
HTTP	Exemplo de code	Quando
400	`INVALID_REQUEST`	Requisição inválida: fieldErrors aponta cada campo.
401	`INVALID_API_KEY`	Chave de API ausente, inválida, expirada ou revogada.
403	`SCOPE_MISSING`	Escopo ausente, conta não permitida em X-Account-Id, IP fora da lista ou conta suspensa.
404	`RESOURCE_NOT_FOUND`	Recurso inexistente nesta conta (inclusive recurso de outra conta ou de outro tenant).
409	`IDEMPOTENCY_CONFLICT`	Conflito de idempotência (IDEMPOTENCY_CONFLICT), requisição em andamento com a mesma chave (REQUEST_IN_PROGRESS) ou estado do recurso.
422	`CAPABILITY_UNAVAILABLE`	Regra de negócio ou capacidade indisponível para a conta.
429	`TOO_MANY_REQUESTS`	Limite de requisições da chave atingido (rajada de 100 e 6.000 por minuto). Toda resposta traz RateLimit-Limit, RateLimit-Remaining e RateLimit-Reset; o 429 traz Retry-After em segundos. Aguarde e repita com a mesma Idempotency-Key.

Remover endpoint (cancela entregas pendentes)

DELETE/v1/webhook-endpoints/{id}Implementada

Chave de API (Authorization: Bearer ep_…)· escopo webhooks:write· deleteWebhookEndpoint

Remove o endpoint. Entregas ainda pendentes são canceladas; o histórico de entregas continua consultável pelo evento.

Escopo da chave: webhooks:write.

Idempotência: exige o header Idempotency-Key.

Headers de deleteWebhookEndpoint
Header	Obrigatório	Descrição
`X-Account-Id`	sim	Conta permitida pelos grants do principal.
`Idempotency-Key`	sim	Chave única por intenção (16 a 128 caracteres visíveis). Ao refazer a mesma chamada, repita a mesma chave: o resultado gravado é devolvido. Mesma chave com outro conteúdo responde 409 IDEMPOTENCY_CONFLICT.

Parâmetros de deleteWebhookEndpoint
Parâmetro	Onde	Tipo	Descrição
`id` obrigatório	caminho	Id (texto)	8–160 caracteres · formato ^[A-Za-z0-9_]+$
`Eclipta-Pay-Version`	header	"2026-11-13"	Versão de data do contrato. Opcional; a resposta sempre informa a versão usada. Valor desconhecido responde 400 UNSUPPORTED_API_VERSION.

Exemplo

curl -X DELETE "$ECLIPTA_PAY_API/v1/webhook-endpoints/{id}" \
  -H "Authorization: Bearer $ECLIPTA_PAY_KEY" \
  -H "X-Account-Id: $ECLIPTA_PAY_ACCOUNT" \
  -H "Idempotency-Key: <uma chave por intenção>"

Resposta 204: Sem conteúdo.

Erros

Erros de deleteWebhookEndpoint
HTTP	Exemplo de code	Quando
400	`INVALID_REQUEST`	Requisição inválida: fieldErrors aponta cada campo.
401	`INVALID_API_KEY`	Chave de API ausente, inválida, expirada ou revogada.
403	`SCOPE_MISSING`	Escopo ausente, conta não permitida em X-Account-Id, IP fora da lista ou conta suspensa.
404	`RESOURCE_NOT_FOUND`	Recurso inexistente nesta conta (inclusive recurso de outra conta ou de outro tenant).
409	`IDEMPOTENCY_CONFLICT`	Conflito de idempotência (IDEMPOTENCY_CONFLICT), requisição em andamento com a mesma chave (REQUEST_IN_PROGRESS) ou estado do recurso.
422	`CAPABILITY_UNAVAILABLE`	Regra de negócio ou capacidade indisponível para a conta.
429	`TOO_MANY_REQUESTS`	Limite de requisições da chave atingido (rajada de 100 e 6.000 por minuto). Toda resposta traz RateLimit-Limit, RateLimit-Remaining e RateLimit-Reset; o 429 traz Retry-After em segundos. Aguarde e repita com a mesma Idempotency-Key.

Rotacionar o segredo de assinatura com sobreposição

POST/v1/webhook-endpoints/{id}/rotate-secretImplementada

Chave de API (Authorization: Bearer ep_…)· escopo webhooks:write· rotateWebhookSecret

Gera um novo segredo (exibido só nesta resposta). Durante a sobreposição, cada entrega leva duas assinaturas v1= no header Eclipta-Pay-Signature e as duas versões em Eclipta-Pay-Key-Id, para você trocar o segredo sem perder eventos.

Escopo da chave: webhooks:write.

Idempotência: exige o header Idempotency-Key.

Headers de rotateWebhookSecret
Header	Obrigatório	Descrição
`X-Account-Id`	sim	Conta permitida pelos grants do principal.
`Idempotency-Key`	sim	Chave única por intenção (16 a 128 caracteres visíveis). Ao refazer a mesma chamada, repita a mesma chave: o resultado gravado é devolvido. Mesma chave com outro conteúdo responde 409 IDEMPOTENCY_CONFLICT.

Parâmetros de rotateWebhookSecret
Parâmetro	Onde	Tipo	Descrição
`id` obrigatório	caminho	Id (texto)	8–160 caracteres · formato ^[A-Za-z0-9_]+$
`Eclipta-Pay-Version`	header	"2026-11-13"	Versão de data do contrato. Opcional; a resposta sempre informa a versão usada. Valor desconhecido responde 400 UNSUPPORTED_API_VERSION.

Corpo da requisição

Campos do corpo de rotateWebhookSecret
Campo	Tipo	Descrição
`overlapSeconds`	inteiro	Por quanto tempo o segredo anterior continua assinando junto com o novo (padrão 86400 = 24 h; 0 encerra o anterior na hora). 0 a 604800

Exemplo

curl -X POST "$ECLIPTA_PAY_API/v1/webhook-endpoints/{id}/rotate-secret" \
  -H "Authorization: Bearer $ECLIPTA_PAY_KEY" \
  -H "X-Account-Id: $ECLIPTA_PAY_ACCOUNT" \
  -H "Idempotency-Key: <uma chave por intenção>" \
  -H "Content-Type: application/json" \
  -d '{"overlapSeconds":86400}'

Resposta 200: Sucesso.

Campos da resposta 200 de rotateWebhookSecret
Campo	Tipo	Descrição
`id` obrigatório	Id (texto)	8–160 caracteres · formato ^[A-Za-z0-9_]+$
`url` obrigatório	texto
`description` obrigatório	texto ou nulo
`events` obrigatório	lista de texto
`status` obrigatório	"ACTIVE" \| "DISABLED" \| "AUTO_DISABLED"	ACTIVE recebe; DISABLED foi pausado pelo integrador; AUTO_DISABLED foi desativado após 3 dias seguidos de falhas.
`apiVersion` obrigatório	"2026-11-13"
`secretVersion` obrigatório	inteiro	Versão do segredo atual; é o valor do header Eclipta-Pay-Key-Id. 1 a 9007199254740991
`previousSecretVersion` obrigatório	inteiro ou nulo
`previousSecretExpiresAt` obrigatório	data e hora (ISO 8601) ou nulo	Até quando o segredo anterior ainda assina (rotação com sobreposição).
`consecutiveFailures` obrigatório	inteiro	0 a 9007199254740991
`failingSince` obrigatório	data e hora (ISO 8601) ou nulo
`lastSuccessAt` obrigatório	data e hora (ISO 8601) ou nulo
`lastFailureAt` obrigatório	data e hora (ISO 8601) ou nulo
`disabledAt` obrigatório	data e hora (ISO 8601) ou nulo
`disabledReason` obrigatório	"MANUAL" \| "CONSECUTIVE_FAILURES" ou nulo
`createdAt` obrigatório	data e hora (ISO 8601)	formato ^(?:(?:\d\d[2468][048]\|\d\d[13579][26]\|\d\d0[48]\|[02468][048]00\|[13579][26]00)-02-29\|\d{4}-(?:(?:0[13578]\|1[02])-(?:0[1-9]\|[12]\d\|3[01])\|(?:0[469]\|11)-(?:0[1-9]\|[12]\d\|30)\|(?:02)-(?:0[1-9]\|1\d\|2[0-8])))T(?:(?:[01]\d\|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z\|([+-](?:[01]\d\|2[0-3]):[0-5]\d)))$
`updatedAt` obrigatório	data e hora (ISO 8601)	formato ^(?:(?:\d\d[2468][048]\|\d\d[13579][26]\|\d\d0[48]\|[02468][048]00\|[13579][26]00)-02-29\|\d{4}-(?:(?:0[13578]\|1[02])-(?:0[1-9]\|[12]\d\|3[01])\|(?:0[469]\|11)-(?:0[1-9]\|[12]\d\|30)\|(?:02)-(?:0[1-9]\|1\d\|2[0-8])))T(?:(?:[01]\d\|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z\|([+-](?:[01]\d\|2[0-3]):[0-5]\d)))$
`secret`	texto	Segredo de assinatura. Exibido só na resposta da criação e da rotação; guarde-o com segurança. formato ^whsec_.*

Exemplo 200

{
  "id": "whk_01JDY9A1B2C3D4E5F6G7H8J9KF",
  "url": "https://loja.exemplo.com.br/webhooks/eclipta",
  "description": "Produção da loja",
  "events": [
    "payment.confirmed",
    "order.payment_completed"
  ],
  "status": "ACTIVE",
  "apiVersion": "2026-11-13",
  "secretVersion": 2,
  "previousSecretVersion": 1,
  "previousSecretExpiresAt": "2026-11-14T13:00:00.000Z",
  "consecutiveFailures": 0,
  "failingSince": null,
  "lastSuccessAt": null,
  "lastFailureAt": null,
  "disabledAt": null,
  "disabledReason": null,
  "createdAt": "2026-11-13T13:00:00.000Z",
  "updatedAt": "2026-11-13T13:00:00.000Z",
  "secret": "whsec_Rotacionado9xAm9lE0nLy7cT2vK4pQ8wZ1sB6dF5"
}

Erros

Erros de rotateWebhookSecret
HTTP	Exemplo de code	Quando
400	`INVALID_REQUEST`	Requisição inválida: fieldErrors aponta cada campo.
401	`INVALID_API_KEY`	Chave de API ausente, inválida, expirada ou revogada.
403	`SCOPE_MISSING`	Escopo ausente, conta não permitida em X-Account-Id, IP fora da lista ou conta suspensa.
404	`RESOURCE_NOT_FOUND`	Recurso inexistente nesta conta (inclusive recurso de outra conta ou de outro tenant).
409	`IDEMPOTENCY_CONFLICT`	Conflito de idempotência (IDEMPOTENCY_CONFLICT), requisição em andamento com a mesma chave (REQUEST_IN_PROGRESS) ou estado do recurso.
422	`CAPABILITY_UNAVAILABLE`	Regra de negócio ou capacidade indisponível para a conta.
429	`TOO_MANY_REQUESTS`	Limite de requisições da chave atingido (rajada de 100 e 6.000 por minuto). Toda resposta traz RateLimit-Limit, RateLimit-Remaining e RateLimit-Reset; o 429 traz Retry-After em segundos. Aguarde e repita com a mesma Idempotency-Key.

Enviar evento de teste ao endpoint

POST/v1/webhook-endpoints/{id}/testImplementada

Chave de API (Authorization: Bearer ep_…)· escopo webhooks:write· sendWebhookTest

Enfileira um evento webhook_endpoint.test só para este endpoint, com assinatura real. Útil para validar a verificação no seu servidor. Não representa mudança financeira.

Escopo da chave: webhooks:write.

Idempotência: exige o header Idempotency-Key.

Headers de sendWebhookTest
Header	Obrigatório	Descrição
`X-Account-Id`	sim	Conta permitida pelos grants do principal.
`Idempotency-Key`	sim	Chave única por intenção (16 a 128 caracteres visíveis). Ao refazer a mesma chamada, repita a mesma chave: o resultado gravado é devolvido. Mesma chave com outro conteúdo responde 409 IDEMPOTENCY_CONFLICT.

Parâmetros de sendWebhookTest
Parâmetro	Onde	Tipo	Descrição
`id` obrigatório	caminho	Id (texto)	8–160 caracteres · formato ^[A-Za-z0-9_]+$
`Eclipta-Pay-Version`	header	"2026-11-13"	Versão de data do contrato. Opcional; a resposta sempre informa a versão usada. Valor desconhecido responde 400 UNSUPPORTED_API_VERSION.

Exemplo

curl -X POST "$ECLIPTA_PAY_API/v1/webhook-endpoints/{id}/test" \
  -H "Authorization: Bearer $ECLIPTA_PAY_KEY" \
  -H "X-Account-Id: $ECLIPTA_PAY_ACCOUNT" \
  -H "Idempotency-Key: <uma chave por intenção>"

Resposta 202: Aceito: a intenção foi registrada; acompanhe o resultado (não é transação concluída).

Campos da resposta 202 de sendWebhookTest
Campo	Tipo	Descrição
`id` obrigatório	Id (texto)	8–160 caracteres · formato ^[A-Za-z0-9_]+$
`eventId` obrigatório	Id (texto)	8–160 caracteres · formato ^[A-Za-z0-9_]+$
`eventType` obrigatório	texto
`endpointId` obrigatório	Id (texto)	8–160 caracteres · formato ^[A-Za-z0-9_]+$
`state` obrigatório	"PENDING" \| "SENDING" \| "SUCCEEDED" \| "FAILED" \| "CANCELLED"
`attempts` obrigatório	inteiro	0 a 9007199254740991
`maxAttempts` obrigatório	inteiro	1 a 9007199254740991
`nextAttemptAt` obrigatório	data e hora (ISO 8601) ou nulo
`lastAttemptAt` obrigatório	data e hora (ISO 8601) ou nulo
`lastHttpStatus` obrigatório	inteiro ou nulo
`lastErrorCode` obrigatório	texto ou nulo
`replayCount` obrigatório	inteiro	0 a 9007199254740991
`createdAt` obrigatório	data e hora (ISO 8601)	formato ^(?:(?:\d\d[2468][048]\|\d\d[13579][26]\|\d\d0[48]\|[02468][048]00\|[13579][26]00)-02-29\|\d{4}-(?:(?:0[13578]\|1[02])-(?:0[1-9]\|[12]\d\|3[01])\|(?:0[469]\|11)-(?:0[1-9]\|[12]\d\|30)\|(?:02)-(?:0[1-9]\|1\d\|2[0-8])))T(?:(?:[01]\d\|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z\|([+-](?:[01]\d\|2[0-3]):[0-5]\d)))$
`attemptLog`	lista de DeliveryAttempt	Tentativas registradas (só na consulta individual).
`attemptLog[].sequence` obrigatório	inteiro	1 a 9007199254740991
`attemptLog[].trigger` obrigatório	"AUTOMATIC" \| "REPLAY" \| "TEST"
`attemptLog[].startedAt` obrigatório	data e hora (ISO 8601)	formato ^(?:(?:\d\d[2468][048]\|\d\d[13579][26]\|\d\d0[48]\|[02468][048]00\|[13579][26]00)-02-29\|\d{4}-(?:(?:0[13578]\|1[02])-(?:0[1-9]\|[12]\d\|3[01])\|(?:0[469]\|11)-(?:0[1-9]\|[12]\d\|30)\|(?:02)-(?:0[1-9]\|1\d\|2[0-8])))T(?:(?:[01]\d\|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z\|([+-](?:[01]\d\|2[0-3]):[0-5]\d)))$
`attemptLog[].durationMs` obrigatório	inteiro ou nulo
`attemptLog[].outcome` obrigatório	"SUCCEEDED" \| "HTTP_ERROR" \| "REDIRECT_NOT_FOLLOWED" \| "TIMEOUT" \| "NETWORK_ERROR" \| "DESTINATION_BLOCKED" \| "RESPONSE_TOO_LARGE" \| "INTERRUPTED"
`attemptLog[].httpStatus` obrigatório	inteiro ou nulo
`attemptLog[].errorCode` obrigatório	texto ou nulo
`attemptLog[].responseExcerpt` obrigatório	texto ou nulo	Até 1 KB do início da resposta, com sequências que parecem documentos, cartões, e-mails ou credenciais mascaradas.

Exemplo 202

{
  "id": "whd_01JDY9B1B2C3D4E5F6G7H8J9KG",
  "eventId": "evt_01JDY9C1B2C3D4E5F6G7H8J9KH",
  "eventType": "webhook_endpoint.test",
  "endpointId": "whk_01JDY9A1B2C3D4E5F6G7H8J9KF",
  "state": "PENDING",
  "attempts": 0,
  "maxAttempts": 9,
  "nextAttemptAt": "2026-11-13T13:00:00.000Z",
  "lastAttemptAt": null,
  "lastHttpStatus": null,
  "lastErrorCode": null,
  "replayCount": 0,
  "createdAt": "2026-11-13T13:00:00.000Z"
}

Erros

Erros de sendWebhookTest
HTTP	Exemplo de code	Quando
400	`INVALID_REQUEST`	Requisição inválida: fieldErrors aponta cada campo.
401	`INVALID_API_KEY`	Chave de API ausente, inválida, expirada ou revogada.
403	`SCOPE_MISSING`	Escopo ausente, conta não permitida em X-Account-Id, IP fora da lista ou conta suspensa.
404	`RESOURCE_NOT_FOUND`	Recurso inexistente nesta conta (inclusive recurso de outra conta ou de outro tenant).
409	`IDEMPOTENCY_CONFLICT`	Conflito de idempotência (IDEMPOTENCY_CONFLICT), requisição em andamento com a mesma chave (REQUEST_IN_PROGRESS) ou estado do recurso.
422	`CAPABILITY_UNAVAILABLE`	Regra de negócio ou capacidade indisponível para a conta.
429	`TOO_MANY_REQUESTS`	Limite de requisições da chave atingido (rajada de 100 e 6.000 por minuto). Toda resposta traz RateLimit-Limit, RateLimit-Remaining e RateLimit-Reset; o 429 traz Retry-After em segundos. Aguarde e repita com a mesma Idempotency-Key.

Listar entregas de webhook

GET/v1/webhook-deliveriesImplementada

Chave de API (Authorization: Bearer ep_…)· escopo webhooks:write· listWebhookDeliveries

Lista entregas (uma por evento × endpoint), com filtros por endpoint, evento e situação.

Escopo da chave: webhooks:write.

Headers de listWebhookDeliveries
Header	Obrigatório	Descrição
`X-Account-Id`	sim	Conta permitida pelos grants do principal.

Parâmetros de listWebhookDeliveries
Parâmetro	Onde	Tipo	Descrição
`cursor`	query	texto	0–200 caracteres
`limit`	query	inteiro	1 a 100 · padrão 20
`endpointId`	query	Id (texto)	8–160 caracteres · formato ^[A-Za-z0-9_]+$
`eventId`	query	Id (texto)	8–160 caracteres · formato ^[A-Za-z0-9_]+$
`state`	query	"PENDING" \| "SENDING" \| "SUCCEEDED" \| "FAILED" \| "CANCELLED"
`Eclipta-Pay-Version`	header	"2026-11-13"	Versão de data do contrato. Opcional; a resposta sempre informa a versão usada. Valor desconhecido responde 400 UNSUPPORTED_API_VERSION.

Exemplo

curl -X GET "$ECLIPTA_PAY_API/v1/webhook-deliveries" \
  -H "Authorization: Bearer $ECLIPTA_PAY_KEY" \
  -H "X-Account-Id: $ECLIPTA_PAY_ACCOUNT"

Resposta 200: Sucesso.

Campos da resposta 200 de listWebhookDeliveries
Campo	Tipo	Descrição
`data` obrigatório	lista de Delivery
`data[].id` obrigatório	Id (texto)	8–160 caracteres · formato ^[A-Za-z0-9_]+$
`data[].eventId` obrigatório	Id (texto)	8–160 caracteres · formato ^[A-Za-z0-9_]+$
`data[].eventType` obrigatório	texto
`data[].endpointId` obrigatório	Id (texto)	8–160 caracteres · formato ^[A-Za-z0-9_]+$
`data[].state` obrigatório	"PENDING" \| "SENDING" \| "SUCCEEDED" \| "FAILED" \| "CANCELLED"
`data[].attempts` obrigatório	inteiro	0 a 9007199254740991
`data[].maxAttempts` obrigatório	inteiro	1 a 9007199254740991
`data[].nextAttemptAt` obrigatório	data e hora (ISO 8601) ou nulo
`data[].lastAttemptAt` obrigatório	data e hora (ISO 8601) ou nulo
`data[].lastHttpStatus` obrigatório	inteiro ou nulo
`data[].lastErrorCode` obrigatório	texto ou nulo
`data[].replayCount` obrigatório	inteiro	0 a 9007199254740991
`data[].createdAt` obrigatório	data e hora (ISO 8601)	formato ^(?:(?:\d\d[2468][048]\|\d\d[13579][26]\|\d\d0[48]\|[02468][048]00\|[13579][26]00)-02-29\|\d{4}-(?:(?:0[13578]\|1[02])-(?:0[1-9]\|[12]\d\|3[01])\|(?:0[469]\|11)-(?:0[1-9]\|[12]\d\|30)\|(?:02)-(?:0[1-9]\|1\d\|2[0-8])))T(?:(?:[01]\d\|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z\|([+-](?:[01]\d\|2[0-3]):[0-5]\d)))$
`data[].attemptLog`	lista de DeliveryAttempt	Tentativas registradas (só na consulta individual).
`data[].attemptLog[].sequence` obrigatório	inteiro	1 a 9007199254740991
`data[].attemptLog[].trigger` obrigatório	"AUTOMATIC" \| "REPLAY" \| "TEST"
`data[].attemptLog[].startedAt` obrigatório	data e hora (ISO 8601)	formato ^(?:(?:\d\d[2468][048]\|\d\d[13579][26]\|\d\d0[48]\|[02468][048]00\|[13579][26]00)-02-29\|\d{4}-(?:(?:0[13578]\|1[02])-(?:0[1-9]\|[12]\d\|3[01])\|(?:0[469]\|11)-(?:0[1-9]\|[12]\d\|30)\|(?:02)-(?:0[1-9]\|1\d\|2[0-8])))T(?:(?:[01]\d\|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z\|([+-](?:[01]\d\|2[0-3]):[0-5]\d)))$
`data[].attemptLog[].durationMs` obrigatório	inteiro ou nulo
`data[].attemptLog[].outcome` obrigatório	"SUCCEEDED" \| "HTTP_ERROR" \| "REDIRECT_NOT_FOLLOWED" \| "TIMEOUT" \| "NETWORK_ERROR" \| "DESTINATION_BLOCKED" \| "RESPONSE_TOO_LARGE" \| "INTERRUPTED"
`data[].attemptLog[].httpStatus` obrigatório	inteiro ou nulo
`data[].attemptLog[].errorCode` obrigatório	texto ou nulo
`data[].attemptLog[].responseExcerpt` obrigatório	texto ou nulo	Até 1 KB do início da resposta, com sequências que parecem documentos, cartões, e-mails ou credenciais mascaradas.
`nextCursor` obrigatório	texto ou nulo

Exemplo 200

{
  "data": [
    {
      "id": "whd_01JDY9B1B2C3D4E5F6G7H8J9KG",
      "eventId": "evt_01JDY9C1B2C3D4E5F6G7H8J9KH",
      "eventType": "order.payment_completed",
      "endpointId": "whk_01JDY9A1B2C3D4E5F6G7H8J9KF",
      "state": "SUCCEEDED",
      "attempts": 1,
      "maxAttempts": 9,
      "nextAttemptAt": null,
      "lastAttemptAt": "2026-11-13T13:00:00.000Z",
      "lastHttpStatus": 200,
      "lastErrorCode": null,
      "replayCount": 0,
      "createdAt": "2026-11-13T13:00:00.000Z"
    }
  ],
  "nextCursor": null
}

Erros

Erros de listWebhookDeliveries
HTTP	Exemplo de code	Quando
400	`INVALID_REQUEST`	Requisição inválida: fieldErrors aponta cada campo.
401	`INVALID_API_KEY`	Chave de API ausente, inválida, expirada ou revogada.
403	`SCOPE_MISSING`	Escopo ausente, conta não permitida em X-Account-Id, IP fora da lista ou conta suspensa.
429	`TOO_MANY_REQUESTS`	Limite de requisições da chave atingido (rajada de 100 e 6.000 por minuto). Toda resposta traz RateLimit-Limit, RateLimit-Remaining e RateLimit-Reset; o 429 traz Retry-After em segundos. Aguarde e repita com a mesma Idempotency-Key.

Consultar entrega e tentativas

GET/v1/webhook-deliveries/{id}Implementada

Chave de API (Authorization: Bearer ep_…)· escopo webhooks:write· getWebhookDelivery

Entrega com o registro de cada tentativa: status HTTP, duração, resultado e até 1 KB do início da resposta, com dados que parecem sensíveis mascarados.

Escopo da chave: webhooks:write.

Headers de getWebhookDelivery
Header	Obrigatório	Descrição
`X-Account-Id`	sim	Conta permitida pelos grants do principal.

Parâmetros de getWebhookDelivery
Parâmetro	Onde	Tipo	Descrição
`id` obrigatório	caminho	Id (texto)	8–160 caracteres · formato ^[A-Za-z0-9_]+$
`Eclipta-Pay-Version`	header	"2026-11-13"	Versão de data do contrato. Opcional; a resposta sempre informa a versão usada. Valor desconhecido responde 400 UNSUPPORTED_API_VERSION.

Exemplo

curl -X GET "$ECLIPTA_PAY_API/v1/webhook-deliveries/{id}" \
  -H "Authorization: Bearer $ECLIPTA_PAY_KEY" \
  -H "X-Account-Id: $ECLIPTA_PAY_ACCOUNT"

Resposta 200: Sucesso.

Campos da resposta 200 de getWebhookDelivery
Campo	Tipo	Descrição
`id` obrigatório	Id (texto)	8–160 caracteres · formato ^[A-Za-z0-9_]+$
`eventId` obrigatório	Id (texto)	8–160 caracteres · formato ^[A-Za-z0-9_]+$
`eventType` obrigatório	texto
`endpointId` obrigatório	Id (texto)	8–160 caracteres · formato ^[A-Za-z0-9_]+$
`state` obrigatório	"PENDING" \| "SENDING" \| "SUCCEEDED" \| "FAILED" \| "CANCELLED"
`attempts` obrigatório	inteiro	0 a 9007199254740991
`maxAttempts` obrigatório	inteiro	1 a 9007199254740991
`nextAttemptAt` obrigatório	data e hora (ISO 8601) ou nulo
`lastAttemptAt` obrigatório	data e hora (ISO 8601) ou nulo
`lastHttpStatus` obrigatório	inteiro ou nulo
`lastErrorCode` obrigatório	texto ou nulo
`replayCount` obrigatório	inteiro	0 a 9007199254740991
`createdAt` obrigatório	data e hora (ISO 8601)	formato ^(?:(?:\d\d[2468][048]\|\d\d[13579][26]\|\d\d0[48]\|[02468][048]00\|[13579][26]00)-02-29\|\d{4}-(?:(?:0[13578]\|1[02])-(?:0[1-9]\|[12]\d\|3[01])\|(?:0[469]\|11)-(?:0[1-9]\|[12]\d\|30)\|(?:02)-(?:0[1-9]\|1\d\|2[0-8])))T(?:(?:[01]\d\|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z\|([+-](?:[01]\d\|2[0-3]):[0-5]\d)))$
`attemptLog`	lista de DeliveryAttempt	Tentativas registradas (só na consulta individual).
`attemptLog[].sequence` obrigatório	inteiro	1 a 9007199254740991
`attemptLog[].trigger` obrigatório	"AUTOMATIC" \| "REPLAY" \| "TEST"
`attemptLog[].startedAt` obrigatório	data e hora (ISO 8601)	formato ^(?:(?:\d\d[2468][048]\|\d\d[13579][26]\|\d\d0[48]\|[02468][048]00\|[13579][26]00)-02-29\|\d{4}-(?:(?:0[13578]\|1[02])-(?:0[1-9]\|[12]\d\|3[01])\|(?:0[469]\|11)-(?:0[1-9]\|[12]\d\|30)\|(?:02)-(?:0[1-9]\|1\d\|2[0-8])))T(?:(?:[01]\d\|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z\|([+-](?:[01]\d\|2[0-3]):[0-5]\d)))$
`attemptLog[].durationMs` obrigatório	inteiro ou nulo
`attemptLog[].outcome` obrigatório	"SUCCEEDED" \| "HTTP_ERROR" \| "REDIRECT_NOT_FOLLOWED" \| "TIMEOUT" \| "NETWORK_ERROR" \| "DESTINATION_BLOCKED" \| "RESPONSE_TOO_LARGE" \| "INTERRUPTED"
`attemptLog[].httpStatus` obrigatório	inteiro ou nulo
`attemptLog[].errorCode` obrigatório	texto ou nulo
`attemptLog[].responseExcerpt` obrigatório	texto ou nulo	Até 1 KB do início da resposta, com sequências que parecem documentos, cartões, e-mails ou credenciais mascaradas.

Exemplo 200

{
  "id": "whd_01JDY9B1B2C3D4E5F6G7H8J9KG",
  "eventId": "evt_01JDY9C1B2C3D4E5F6G7H8J9KH",
  "eventType": "order.payment_completed",
  "endpointId": "whk_01JDY9A1B2C3D4E5F6G7H8J9KF",
  "state": "SUCCEEDED",
  "attempts": 1,
  "maxAttempts": 9,
  "nextAttemptAt": null,
  "lastAttemptAt": "2026-11-13T13:00:00.000Z",
  "lastHttpStatus": 200,
  "lastErrorCode": null,
  "replayCount": 0,
  "createdAt": "2026-11-13T13:00:00.000Z",
  "attemptLog": [
    {
      "sequence": 1,
      "trigger": "AUTOMATIC",
      "startedAt": "2026-11-13T13:00:00.000Z",
      "durationMs": 182,
      "outcome": "SUCCEEDED",
      "httpStatus": 200,
      "errorCode": null,
      "responseExcerpt": "{\"received\":true}"
    }
  ]
}

Erros

Erros de getWebhookDelivery
HTTP	Exemplo de code	Quando
400	`INVALID_REQUEST`	Requisição inválida: fieldErrors aponta cada campo.
401	`INVALID_API_KEY`	Chave de API ausente, inválida, expirada ou revogada.
403	`SCOPE_MISSING`	Escopo ausente, conta não permitida em X-Account-Id, IP fora da lista ou conta suspensa.
404	`RESOURCE_NOT_FOUND`	Recurso inexistente nesta conta (inclusive recurso de outra conta ou de outro tenant).
429	`TOO_MANY_REQUESTS`	Limite de requisições da chave atingido (rajada de 100 e 6.000 por minuto). Toda resposta traz RateLimit-Limit, RateLimit-Remaining e RateLimit-Reset; o 429 traz Retry-After em segundos. Aguarde e repita com a mesma Idempotency-Key.

Reenviar entrega (mesmo eventId)

POST/v1/webhook-deliveries/{id}/replayImplementada

Chave de API (Authorization: Bearer ep_…)· escopo webhooks:write· replayWebhookDelivery

Reenvia a entrega com o mesmo eventId e nova assinatura (novo timestamp). O receptor deve deduplicar por eventId e aplicar o efeito uma única vez. O reenvio é auditado e não cria outra entrega para o mesmo evento × endpoint.

Escopo da chave: webhooks:write.

Idempotência: exige o header Idempotency-Key.

Headers de replayWebhookDelivery
Header	Obrigatório	Descrição
`X-Account-Id`	sim	Conta permitida pelos grants do principal.
`Idempotency-Key`	sim	Chave única por intenção (16 a 128 caracteres visíveis). Ao refazer a mesma chamada, repita a mesma chave: o resultado gravado é devolvido. Mesma chave com outro conteúdo responde 409 IDEMPOTENCY_CONFLICT.

Parâmetros de replayWebhookDelivery
Parâmetro	Onde	Tipo	Descrição
`id` obrigatório	caminho	Id (texto)	8–160 caracteres · formato ^[A-Za-z0-9_]+$
`Eclipta-Pay-Version`	header	"2026-11-13"	Versão de data do contrato. Opcional; a resposta sempre informa a versão usada. Valor desconhecido responde 400 UNSUPPORTED_API_VERSION.

Exemplo

curl -X POST "$ECLIPTA_PAY_API/v1/webhook-deliveries/{id}/replay" \
  -H "Authorization: Bearer $ECLIPTA_PAY_KEY" \
  -H "X-Account-Id: $ECLIPTA_PAY_ACCOUNT" \
  -H "Idempotency-Key: <uma chave por intenção>"

Resposta 202: Aceito: a intenção foi registrada; acompanhe o resultado (não é transação concluída).

Campos da resposta 202 de replayWebhookDelivery
Campo	Tipo	Descrição
`id` obrigatório	Id (texto)	8–160 caracteres · formato ^[A-Za-z0-9_]+$
`eventId` obrigatório	Id (texto)	8–160 caracteres · formato ^[A-Za-z0-9_]+$
`eventType` obrigatório	texto
`endpointId` obrigatório	Id (texto)	8–160 caracteres · formato ^[A-Za-z0-9_]+$
`state` obrigatório	"PENDING" \| "SENDING" \| "SUCCEEDED" \| "FAILED" \| "CANCELLED"
`attempts` obrigatório	inteiro	0 a 9007199254740991
`maxAttempts` obrigatório	inteiro	1 a 9007199254740991
`nextAttemptAt` obrigatório	data e hora (ISO 8601) ou nulo
`lastAttemptAt` obrigatório	data e hora (ISO 8601) ou nulo
`lastHttpStatus` obrigatório	inteiro ou nulo
`lastErrorCode` obrigatório	texto ou nulo
`replayCount` obrigatório	inteiro	0 a 9007199254740991
`createdAt` obrigatório	data e hora (ISO 8601)	formato ^(?:(?:\d\d[2468][048]\|\d\d[13579][26]\|\d\d0[48]\|[02468][048]00\|[13579][26]00)-02-29\|\d{4}-(?:(?:0[13578]\|1[02])-(?:0[1-9]\|[12]\d\|3[01])\|(?:0[469]\|11)-(?:0[1-9]\|[12]\d\|30)\|(?:02)-(?:0[1-9]\|1\d\|2[0-8])))T(?:(?:[01]\d\|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z\|([+-](?:[01]\d\|2[0-3]):[0-5]\d)))$
`attemptLog`	lista de DeliveryAttempt	Tentativas registradas (só na consulta individual).
`attemptLog[].sequence` obrigatório	inteiro	1 a 9007199254740991
`attemptLog[].trigger` obrigatório	"AUTOMATIC" \| "REPLAY" \| "TEST"
`attemptLog[].startedAt` obrigatório	data e hora (ISO 8601)	formato ^(?:(?:\d\d[2468][048]\|\d\d[13579][26]\|\d\d0[48]\|[02468][048]00\|[13579][26]00)-02-29\|\d{4}-(?:(?:0[13578]\|1[02])-(?:0[1-9]\|[12]\d\|3[01])\|(?:0[469]\|11)-(?:0[1-9]\|[12]\d\|30)\|(?:02)-(?:0[1-9]\|1\d\|2[0-8])))T(?:(?:[01]\d\|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z\|([+-](?:[01]\d\|2[0-3]):[0-5]\d)))$
`attemptLog[].durationMs` obrigatório	inteiro ou nulo
`attemptLog[].outcome` obrigatório	"SUCCEEDED" \| "HTTP_ERROR" \| "REDIRECT_NOT_FOLLOWED" \| "TIMEOUT" \| "NETWORK_ERROR" \| "DESTINATION_BLOCKED" \| "RESPONSE_TOO_LARGE" \| "INTERRUPTED"
`attemptLog[].httpStatus` obrigatório	inteiro ou nulo
`attemptLog[].errorCode` obrigatório	texto ou nulo
`attemptLog[].responseExcerpt` obrigatório	texto ou nulo	Até 1 KB do início da resposta, com sequências que parecem documentos, cartões, e-mails ou credenciais mascaradas.

Exemplo 202

{
  "id": "whd_01JDY9B1B2C3D4E5F6G7H8J9KG",
  "eventId": "evt_01JDY9C1B2C3D4E5F6G7H8J9KH",
  "eventType": "order.payment_completed",
  "endpointId": "whk_01JDY9A1B2C3D4E5F6G7H8J9KF",
  "state": "PENDING",
  "attempts": 1,
  "maxAttempts": 9,
  "nextAttemptAt": "2026-11-13T13:00:00.000Z",
  "lastAttemptAt": "2026-11-13T13:00:00.000Z",
  "lastHttpStatus": 200,
  "lastErrorCode": null,
  "replayCount": 1,
  "createdAt": "2026-11-13T13:00:00.000Z"
}

Erros

Erros de replayWebhookDelivery
HTTP	Exemplo de code	Quando
400	`INVALID_REQUEST`	Requisição inválida: fieldErrors aponta cada campo.
401	`INVALID_API_KEY`	Chave de API ausente, inválida, expirada ou revogada.
403	`SCOPE_MISSING`	Escopo ausente, conta não permitida em X-Account-Id, IP fora da lista ou conta suspensa.
404	`RESOURCE_NOT_FOUND`	Recurso inexistente nesta conta (inclusive recurso de outra conta ou de outro tenant).
409	`IDEMPOTENCY_CONFLICT`	Conflito de idempotência (IDEMPOTENCY_CONFLICT), requisição em andamento com a mesma chave (REQUEST_IN_PROGRESS) ou estado do recurso.
422	`CAPABILITY_UNAVAILABLE`	Regra de negócio ou capacidade indisponível para a conta.
429	`TOO_MANY_REQUESTS`	Limite de requisições da chave atingido (rajada de 100 e 6.000 por minuto). Toda resposta traz RateLimit-Limit, RateLimit-Remaining e RateLimit-Reset; o 429 traz Retry-After em segundos. Aguarde e repita com a mesma Idempotency-Key.

Todas as rotas