Webhooks do Pagar.me

Audita os avisos que o gateway enviou à loja e reprocessa um aviso que não conseguiu atualizar o pedido.

O Pagar.me avisa a plataforma de cada mudança de cobrança (paga, recusada, estornada...) com uma chamada a POST /api/v1/webhooks/pagarme. Cada aviso recebido é guardado, e depois a plataforma tenta atualizar o status do pedido conforme o de-para. Se algo falha no meio, o pedido pode ficar parado em "aguardando pagamento" mesmo com o dinheiro já recebido. Estas duas rotas mostram o registro de avisos e permitem reprocessar um deles. Exigem o módulo pagarme e o privilégio manage_payments ou view_payments.

Quando a loja tem o segredo de webhook (secret_key) configurado, avisos sem assinatura válida são recusados antes de serem processados. Um aviso repetido do mesmo evento é reconhecido e ignorado.

Listar webhooks

Devolve os avisos recebidos, dos mais novos para os mais antigos.

GET/api/v1/admin/pagarme/webhooksAdmin

Lista os webhooks recebidos do Pagar.me

Parâmetros de consulta

processedboolean

truefalse

true: só os já processados. false: só os pendentes. Ausente: todos. Aceita também 1, 0, t, f.

pageintegerpadrão: 1

Página, a partir de 1.

per_pageintegerpadrão: 20

Itens por página, de 1 a 100. Acima de 100 vale 100.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/pagarme/webhooks?processed=false&per_page=20" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Webhooks devolvidos

json

{
  "webhooks": [
    {
      "id": 5,
      "event_id": "hook_Zq3xExample0001",
      "event_type": "charge.paid",
      "charge_id": "ch_Z1dxXYKcNWcnw547",
      "processed": false,
      "error_message": "order not found for charge",
      "created_at": "2026-10-11T22:00:12Z"
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 20
}

Campos da resposta

webhooksarray

Avisos da página.

totalinteger

Total que casa com o filtro.

pageinteger

Página devolvida.

per_pageinteger

Tamanho de página aplicado.

idinteger

Id interno do aviso (número inteiro). É o que o reprocessamento recebe.

event_idstring

Id do evento no gateway. Vazio se o gateway não enviou.

event_typestring

Tipo do evento, por exemplo charge.paid ou charge.refunded.

charge_idstring

Cobrança do gateway (ch_...), quando o evento traz uma.

processedboolean

Se o aviso foi processado.

error_messagestring

Falha registrada, vazia quando está tudo certo. Um aviso pode estar processed: true e ainda assim trazer error_message, quando a cobrança foi registrada mas a atualização do pedido falhou.

created_atstring

Quando o aviso chegou, RFC 3339.

Erros

Status	Quando	Corpo
400	`processed` com valor que não é booleano	`{"error":"invalid processed filter","detail":"..."}`
500	Falha de consulta	`{"error":"failed to list webhooks","detail":"..."}`

Reprocessar um webhook

Lê o aviso guardado, refaz o processamento da cobrança e roda de novo a regra que atualiza o status do pedido. Use depois de corrigir a causa da falha, por exemplo ao criar o status de pedido que faltava no de-para.

POST/api/v1/admin/pagarme/webhooks/{id}/reprocessAdmin

Reprocessa um webhook do Pagar.me

Parâmetros de caminho

idintegerobrigatório

Id interno do aviso, como aparece na listagem.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/pagarme/webhooks/5/reprocess" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Webhook reprocessado

json

{ "message": "webhook reprocessed" }

Em caso de sucesso o aviso passa a processed: true e o error_message é limpo.

Erros

Status	Quando	Corpo
400	`id` que não é inteiro	`{"error":"invalid webhook id","detail":"..."}`
422	Aviso inexistente, ou o processamento falhou de novo	`{"error":"failed to reprocess webhook","detail":"pagarme: webhook 99 not found"}`
422	A cobrança foi processada, mas a atualização do pedido falhou	`{"error":"failed to reprocess webhook","detail":"..."}`

Veja também

API atual/Referência completa/Pagar.me

Webhooks do Pagar.me

Audita os avisos que o gateway enviou à loja e reprocessa um aviso que não conseguiu atualizar o pedido.

Listar webhooks

Devolve os avisos recebidos, dos mais novos para os mais antigos.

GET/api/v1/admin/pagarme/webhooksAdmin

Lista os webhooks recebidos do Pagar.me

Parâmetros de consulta

processedboolean

truefalse

true: só os já processados. false: só os pendentes. Ausente: todos. Aceita também 1, 0, t, f.

pageintegerpadrão: 1

Página, a partir de 1.

per_pageintegerpadrão: 20

Itens por página, de 1 a 100. Acima de 100 vale 100.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/pagarme/webhooks?processed=false&per_page=20" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Webhooks devolvidos

json

{
  "webhooks": [
    {
      "id": 5,
      "event_id": "hook_Zq3xExample0001",
      "event_type": "charge.paid",
      "charge_id": "ch_Z1dxXYKcNWcnw547",
      "processed": false,
      "error_message": "order not found for charge",
      "created_at": "2026-10-11T22:00:12Z"
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 20
}

Campos da resposta

webhooksarray

Avisos da página.

totalinteger

Total que casa com o filtro.

pageinteger

Página devolvida.

per_pageinteger

Tamanho de página aplicado.

idinteger

Id interno do aviso (número inteiro). É o que o reprocessamento recebe.

event_idstring

Id do evento no gateway. Vazio se o gateway não enviou.

event_typestring

Tipo do evento, por exemplo charge.paid ou charge.refunded.

charge_idstring

Cobrança do gateway (ch_...), quando o evento traz uma.

processedboolean

Se o aviso foi processado.

error_messagestring

Falha registrada, vazia quando está tudo certo. Um aviso pode estar processed: true e ainda assim trazer error_message, quando a cobrança foi registrada mas a atualização do pedido falhou.

created_atstring

Quando o aviso chegou, RFC 3339.

Erros

Status	Quando	Corpo
400	`processed` com valor que não é booleano	`{"error":"invalid processed filter","detail":"..."}`
500	Falha de consulta	`{"error":"failed to list webhooks","detail":"..."}`

Reprocessar um webhook

POST/api/v1/admin/pagarme/webhooks/{id}/reprocessAdmin

Reprocessa um webhook do Pagar.me

Parâmetros de caminho

idintegerobrigatório

Id interno do aviso, como aparece na listagem.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/pagarme/webhooks/5/reprocess" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Webhook reprocessado

json

{ "message": "webhook reprocessed" }

Em caso de sucesso o aviso passa a processed: true e o error_message é limpo.

Erros

Status	Quando	Corpo
400	`id` que não é inteiro	`{"error":"invalid webhook id","detail":"..."}`
422	Aviso inexistente, ou o processamento falhou de novo	`{"error":"failed to reprocess webhook","detail":"pagarme: webhook 99 not found"}`
422	A cobrança foi processada, mas a atualização do pedido falhou	`{"error":"failed to reprocess webhook","detail":"..."}`