curl --request POST \
--url https://api.sandbox.z2pay.com/v1/webhooks/deliveries/{id}/retry \
--header 'x-api-key: <api-key>'const options = {method: 'POST', headers: {'x-api-key': '<api-key>'}};
fetch('https://api.sandbox.z2pay.com/v1/webhooks/deliveries/{id}/retry', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.sandbox.z2pay.com/v1/webhooks/deliveries/{id}/retry"
headers = {"x-api-key": "<api-key>"}
response = requests.post(url, headers=headers)
print(response.text){
"id": "whd_w2wwfrrrvwx9axbb1wj1bgg75",
"webhookId": "whk_tnuvglgyl74mm7k3cx18mmd6h",
"eventType": "transaction.refused",
"url": "https://api.minhaloja.com.br/webhooks/z2pay",
"payload": {
"id": "whd_w2wwfrrrvwx9axbb1wj1bgg75",
"type": "transaction.refused",
"data": {
"id": "txn_wb8adjjeajavewrebxzvv1wna",
"amount": 9990,
"status": "refused"
},
"occurredAt": "2025-06-29T13:50:00.000Z"
},
"status": "failed",
"attemptCount": 3,
"returnStatus": 500,
"returnData": {
"error": "Internal Server Error"
},
"errorMessage": "Request failed with status code 500",
"lastAttemptAt": "2025-06-29T14:02:30.000Z",
"createdAt": "2025-06-29T13:50:00.000Z",
"updatedAt": "2025-06-29T14:02:30.000Z"
}{
"error": {
"code": "UNAUTHORIZED",
"message": "Invalid API key"
}
}{
"error": {
"code": "NOT_FOUND",
"message": "Delivery not found"
}
}{
"error": "A request with this idempotency key is already being processed"
}{
"error": "Idempotency key already used with a different request body"
}Reprocessar delivery
Reenvia uma entrega já concluída e devolve o desfecho da nova tentativa.
curl --request POST \
--url https://api.sandbox.z2pay.com/v1/webhooks/deliveries/{id}/retry \
--header 'x-api-key: <api-key>'const options = {method: 'POST', headers: {'x-api-key': '<api-key>'}};
fetch('https://api.sandbox.z2pay.com/v1/webhooks/deliveries/{id}/retry', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.sandbox.z2pay.com/v1/webhooks/deliveries/{id}/retry"
headers = {"x-api-key": "<api-key>"}
response = requests.post(url, headers=headers)
print(response.text){
"id": "whd_w2wwfrrrvwx9axbb1wj1bgg75",
"webhookId": "whk_tnuvglgyl74mm7k3cx18mmd6h",
"eventType": "transaction.refused",
"url": "https://api.minhaloja.com.br/webhooks/z2pay",
"payload": {
"id": "whd_w2wwfrrrvwx9axbb1wj1bgg75",
"type": "transaction.refused",
"data": {
"id": "txn_wb8adjjeajavewrebxzvv1wna",
"amount": 9990,
"status": "refused"
},
"occurredAt": "2025-06-29T13:50:00.000Z"
},
"status": "failed",
"attemptCount": 3,
"returnStatus": 500,
"returnData": {
"error": "Internal Server Error"
},
"errorMessage": "Request failed with status code 500",
"lastAttemptAt": "2025-06-29T14:02:30.000Z",
"createdAt": "2025-06-29T13:50:00.000Z",
"updatedAt": "2025-06-29T14:02:30.000Z"
}{
"error": {
"code": "UNAUTHORIZED",
"message": "Invalid API key"
}
}{
"error": {
"code": "NOT_FOUND",
"message": "Delivery not found"
}
}{
"error": "A request with this idempotency key is already being processed"
}{
"error": "Idempotency key already used with a different request body"
}POST /webhooks/deliveries/:id/retry
Faz parte do recurso Webhooks — o cadastro e o catálogo de eventos estão lá.
Reenvia uma entrega para a URL atual do webhook. O caso de uso é o de sempre: seu endpoint
esteve fora do ar, você corrigiu, e agora quer receber o que ficou para trás. Responde 200 com a
entrega relida depois do reenvio.
failed é o caso normal; success também é aceito, para quando você
processou mal e quer o evento de novo. As que ainda estão em curso (pending, retrying)
respondem 409 DELIVERY_ALREADY_RUNNING — a Z2Pay já vai reenviá-las sozinha, sem você pedir.status da resposta ainda pode ser retrying. A entrega é
reenfileirada e relida logo em seguida, então o corpo mostra o estado imediato, não
necessariamente o desfecho. Para saber como terminou, consulte
a entrega alguns instantes depois.id, mesmo occurredAt. Se o recurso
mudou de estado desde então, o payload continua descrevendo o momento do evento, não o de agora.
Um receptor que trate o webhook como aviso e consulte a API pelo id não se incomoda com isso.Limites e recusas
Cada entrega tem 12 tentativas no total: as 7 do ciclo automático mais 5 reprocessamentos manuais. O reenvio recusa com código próprio, para você distinguir o que fazer:| Código | HTTP | O que fazer |
|---|---|---|
DELIVERY_NOT_FOUND | 404 | Conferir o id — ou a entrega é de outra conta |
DELIVERY_ALREADY_RUNNING | 409 | Nada: ela já está sendo processada |
DELIVERY_IS_TEST | 400 | Disparo de teste não se reprocessa; dispare outro pelo painel |
MAX_RETRIES_EXCEEDED | 400 | Reconciliar pela API; esta entrega não sai mais |
WEBHOOK_NOT_FOUND | 404 | O webhook foi removido; recriar e reconciliar pela API |
WEBHOOK_INACTIVE | 400 | Ativar o webhook e tentar de novo |
Exemplo
curl -X POST https://api.sandbox.z2pay.com/v1/webhooks/deliveries/whd_t3ysa1qmxmusn47dhojdraxdi/retry \
-H "x-api-key: SUA_CHAVE_DE_SANDBOX"
{
"id": "whd_t3ysa1qmxmusn47dhojdraxdi",
"webhookId": "whk_k9clfafnldd96dbbxruh34233",
"eventType": "transaction.paid",
"url": "https://meusite.com/webhooks/z2pay",
"payload": {
"id": "whd_t3ysa1qmxmusn47dhojdraxdi",
"type": "transaction.paid",
"data": { "id": "txn_fcfcvfq9ryd6t3yczj6e87gyh" },
"occurredAt": "2026-06-24T13:46:00.000Z"
},
"status": "retrying",
"attemptCount": 7,
"returnStatus": 500,
"returnData": { "error": "internal server error" },
"errorMessage": "Request failed with status code 500",
"lastAttemptAt": "2026-06-25T20:16:00.000Z",
"createdAt": "2026-06-24T13:46:00.000Z",
"updatedAt": "2026-06-26T09:30:00.000Z"
}
Authorizations
API Key da Credential (gerada no Backoffice)
Headers
Chave única para garantir idempotência da requisição
Path Parameters
ID da delivery
Response
Entrega reenviada, com o resultado da nova tentativa
Identificador único do registro.
ID do webhook relacionado ao registro.
Tipo do evento entregue (ex.: transaction.paid).
URL de destino do webhook ou link de download do arquivo.
Conteúdo (payload) enviado na entrega do webhook.
Situação da entrega. Valores: pending, success, failed, retrying.
Número de tentativas de entrega já realizadas.
Código de status HTTP retornado pelo endpoint na entrega.
Corpo da resposta retornada pelo endpoint na entrega.
Mensagem de erro quando o processamento falha.
Data e hora da última tentativa de entrega (ISO 8601).
Data e hora de criação do registro (ISO 8601).
Data e hora da última atualização do registro (ISO 8601).