Webhooks

A PlugToPay entrega notificações assíncronas para as URLs configuradas na sua empresa sempre que ocorre um evento de pagamento ou assinatura. Você pode registrar múltiplos endpoints, cada um inscrito em eventos específicos.

Gerenciar endpoints

Criar endpoint

POST /api/v1/user/company/webhooks
Authorization: Bearer eyJ...
Content-Type: application/json

{
  "url": "https://seusite.com/webhooks/plugtopay",
  "events": ["transaction.approved", "transaction.failed"],
  "enabled": true
}

Resposta (201 Created):

{
  "id": 1,
  "url": "https://seusite.com/webhooks/plugtopay",
  "events": ["transaction.approved", "transaction.failed"],
  "enabled": true,
  "created_at": "2026-06-01T12:00:00+00:00"
}

Listar endpoints

GET /api/v1/user/company/webhooks
Authorization: Bearer eyJ...

Resposta:

{
  "data": [
    {
      "id": 1,
      "url": "https://seusite.com/webhooks/plugtopay",
      "events": ["transaction.approved", "transaction.failed"],
      "enabled": true,
      "created_at": "2026-06-01T12:00:00+00:00"
    }
  ]
}

Ativar / desativar endpoint

PATCH /api/v1/user/company/webhooks/{id}
Authorization: Bearer eyJ...
Content-Type: application/json

{
  "enabled": false
}

Excluir endpoint

DELETE /api/v1/user/company/webhooks/{id}
Authorization: Bearer eyJ...

Eventos disponíveis

Passe um array de eventos ao criar o endpoint. Um endpoint receberá apenas os eventos que estiver inscrito.

Transações

Evento	Descrição
`transaction.approved`	Pagamento aprovado pelo gateway.
`transaction.failed`	Pagamento recusado ou com erro.
`transaction.refunded`	Valor devolvido ao cliente.
`transaction.pending`	Aguardando confirmação (ex.: Pix).

Atenção: transaction.status_update ainda é aceito na criação de webhooks, mas nenhum evento é publicado com esse nome — endpoints inscritos nele não recebem nada. Assine os eventos específicos acima (issue ronierisonsena/plugtopay#51).

Assinaturas

Evento	Descrição
`subscription.created`	Assinatura criada.
`subscription.trial_started`	Período de trial iniciado.
`subscription.trial_ending`	Período de trial próximo do fim.
`subscription.activated`	Assinatura ativada (após trial).
`subscription.payment.success`	Cobrança recorrente confirmada.
`subscription.payment.failed`	Cobrança recorrente recusada.
`subscription.payment.retry`	Cobrança recorrente em retentativa.
`subscription.card_expiring`	Cartão da assinatura prestes a vencer.
`subscription.paused`	Assinatura pausada.
`subscription.resumed`	Assinatura reativada.
`subscription.plan_changed`	Plano da assinatura alterado.
`subscription.canceled`	Assinatura cancelada.
`subscription.past_due`	Assinatura com cobrança em atraso.

Payload

O backend envia um POST para a URL configurada. Para eventos de transação, o corpo é o PaymentResource completo:

{
  "status": "approved",
  "transaction_id": "019ddb56-fbe3-72e1-9f3c-8d0b2faf8f73",
  "amount": 15000,
  "payment_method": "card",
  "attempts": 1,
  "created_at": "2026-04-30T01:23:45+00:00",
  "updated_at": "2026-04-30T01:23:46+00:00",
  "transactions": [ ... ],
  "card": { ... }
}

Retentativas

A PlugToPay reprocessa webhooks com falha automaticamente via WebhookRetryCron. Cada tentativa fica registrada com retry_count e next_retry_at. Você pode acompanhar o status de entrega no detalhe de cada transação no painel.

Campo	Descrição
`status`	`pending`, `delivered`, `failed`
`retry_count`	Número de tentativas realizadas
`next_retry_at`	Próxima tentativa agendada (ISO 8601)

Seu endpoint deve retornar 2xx em até 10 segundos. Respostas fora desse intervalo são tratadas como falha e entram na fila de retenção.

Callbacks de gateway (inbound)

Além dos webhooks de saída para o merchant, a PlugToPay recebe callbacks dos próprios gateways em:

POST /api/v1/webhooks/{gateway}

Esse endpoint é público (sem autenticação) e é usado pelos gateways para notificar mudanças de status assíncronas (ex: PIX confirmado). Você não deve chamar este endpoint diretamente.

Introdução

Orquestração

Pagamentos

Assinaturas

Recursos

Gerenciar endpoints

Criar endpoint

Listar endpoints

Ativar / desativar endpoint

Excluir endpoint

Eventos disponíveis

Transações

Assinaturas

Payload

Retentativas

Callbacks de gateway (inbound)

​Gerenciar endpoints

​Criar endpoint

​Listar endpoints

​Ativar / desativar endpoint

​Excluir endpoint

​Eventos disponíveis

​Transações

​Assinaturas

​Payload

​Retentativas

​Callbacks de gateway (inbound)

Gerenciar endpoints

Criar endpoint

Listar endpoints

Ativar / desativar endpoint

Excluir endpoint

Eventos disponíveis

Transações

Assinaturas

Payload

Retentativas

Callbacks de gateway (inbound)