> ## Documentation Index
> Fetch the complete documentation index at: https://docs.plugtopay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Receba notificações em tempo real sobre eventos de pagamento e assinaturas.

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

```http theme={null}
POST /api/v1/user/company/webhooks
Authorization: Bearer eyJ...
Content-Type: application/json
```

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

**Resposta (`201 Created`):**

```json theme={null}
{
  "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

```http theme={null}
GET /api/v1/user/company/webhooks
Authorization: Bearer eyJ...
```

**Resposta:**

```json theme={null}
{
  "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

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

```json theme={null}
{
  "enabled": false
}
```

### Excluir endpoint

```http theme={null}
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](https://github.com/ronierisonsena/plugtopay/issues/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:

```json theme={null}
{
  "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) |

<Info>
  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.
</Info>

## Callbacks de gateway (inbound)

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

```http theme={null}
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.