> ## Documentation Index
> Fetch the complete documentation index at: https://docs.veepag.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Webhooks
> Eventos enviados pela Veepag para a URL configurada na empresa.
Webhooks ajudam sua aplicação a acompanhar mudanças importantes sem precisar consultar a API o tempo todo.
Quando um evento relevante acontece, a Veepag envia um `POST` para a URL configurada em `company.setting.webhook`. Assim, seu sistema pode reagir a atualizações de transações, assinaturas e cobranças com mais agilidade.
| Configuração | Descrição |
| ------------ | ---------------------------------------- |
| `active` | Indica se o webhook está ativo. |
| `url` | URL que recebe os eventos por HTTP POST. |
## Eventos confirmados
| Evento | Payload enviado hoje |
| ---------------------- | ------------------------------------------------------------- |
| `transaction.created` | `{ "type": "transaction.created", "transaction": { ... } }` |
| `transaction.update` | `{ "type": "transaction.update", "transaction": { ... } }` |
| `subscription.created` | `{ "type": "subscription.created", "subscription": { ... } }` |
| `subscription.update` | `{ "type": "subscription.update", "subscription": { ... } }` |
| `charge.created` | `{ "type": "charge.created", "charge": { ... } }` |
| `charge.update` | `{ "type": "charge.update", "charge": { ... } }` |
O payload de `transaction.created` pode trazer `subscription`, `product` e `client` dentro de `transaction`, quando esses dados estiverem disponíveis no fluxo de criação. No envio atual confirmado, `transaction.update` envia os campos base da transação. O objeto `charge` não é enviado dentro de `transaction` hoje.
Campos opcionais podem não aparecer no JSON quando estiverem `undefined`. Nos exemplos abaixo, usamos `null` apenas para representar campos que podem estar salvos explicitamente como nulos.
## Transaction webhook
### `transaction.created`
```json theme={null}
{
"type": "transaction.created",
"transaction": {
"_id": "transaction_id",
"acquirer": {
"id": "integration_id",
"integrationId": "integration_config_id",
"name": "Nome do adquirente",
"tid": "tid"
},
"amount": {
"currency": "BRL",
"value": 9900
},
"boleto": null,
"chargeId": "charge_id",
"clientId": "client_id",
"code": null,
"companyId": "company_id",
"createdAt": "2026-06-23T12:00:00.000Z",
"feeDetails": null,
"fees": null,
"history": [
{
"date": "2026-06-23T12:00:00.000Z",
"message": "Transação criada",
"status": "PROCESSING"
}
],
"installments": 1,
"lastUpdate": "2026-06-23T12:00:03.000Z",
"message": "Pagamento aprovado",
"message2": null,
"paymentMethod": "CREDIT_CARD",
"paymentMethodId": "payment_method_id",
"paymentMethodOption": null,
"previousData": null,
"productId": "product_id",
"qrCode": null,
"status": "PAID",
"subscriptionId": "subscription_id",
"affiliateId": "affiliate_id",
"metadata": {
"externalId": "pedido-123"
},
"subscription": {
"_id": "subscription_id",
"active": true,
"canceledDate": null,
"clientId": "client_id",
"companyId": "company_id",
"createdAt": "2026-06-23T12:00:00.000Z",
"history": [
{
"date": "2026-06-23T11:59:55.000Z",
"message": "Assinatura criada",
"status": "CREATED"
}
],
"installments": 1,
"lastUpdate": "2026-06-23T12:00:00.000Z",
"metadata": {
"externalId": "assinatura-123"
},
"nextCharge": "2026-07-23T12:00:00.000Z",
"origin": "API",
"paymentMethod": ["CREDIT_CARD"],
"previousData": null,
"productId": "product_id",
"referenceId": "referencia-do-cliente",
"status": "CREATED",
"affiliateId": "affiliate_id",
"checkoutUrl": "https://checkout.veepag.com/..."
},
"product": {
"_id": "product_id",
"active": true,
"charge": {
"amount": 9900
},
"checkout": null,
"companyId": "company_id",
"createdAt": "2026-06-23T12:00:00.000Z",
"deleted": false,
"discount": null,
"notification": null,
"product": {
"title": "Assinatura Veepag",
"price": 99.9
},
"send": null,
"setting": {},
"split": {},
"unsubscription": null
},
"client": {
"_id": "client_id",
"active": true,
"address": {
"additionalDetails": null,
"city": "São Paulo",
"complement": "Apto 101",
"country": "BR",
"neighborhood": "Centro",
"number": "123",
"state": "SP",
"street": "Rua Exemplo",
"zipcode": "01001000"
},
"birth": "1990-01-01",
"charges": null,
"companyId": "company_id",
"cpf": "12345678909",
"createdAt": "2026-06-23T12:00:00.000Z",
"deleted": null,
"device": {
"colorDepth": 24,
"javaEnable": false,
"language": "pt-BR",
"screenHeight": 1080,
"screenWidth": 1920,
"timezoneOffset": 180,
"userAgent": "Mozilla/5.0...",
"javaEnabled": false
},
"doc": "12345678909",
"email": "cliente@exemplo.com",
"gender": null,
"ipAddress": "127.0.0.1",
"lastUpdate": "2026-06-23T12:00:00.000Z",
"name": "Cliente Veepag",
"note": null,
"phone": ["11999999999"],
"referenceId": "cliente-123",
"status": "ACTIVE",
"type": "INDIVIDUAL"
}
}
}
```
### `transaction.update`
```json theme={null}
{
"type": "transaction.update",
"transaction": {
"_id": "transaction_id",
"acquirer": {
"id": "integration_id",
"integrationId": "integration_config_id",
"name": "Nome do adquirente",
"tid": "tid"
},
"amount": {
"currency": "BRL",
"value": 9900
},
"chargeId": "charge_id",
"clientId": "client_id",
"companyId": "company_id",
"createdAt": "2026-06-23T12:00:00.000Z",
"history": [
{
"date": "2026-06-23T12:00:03.000Z",
"message": "Pagamento aprovado",
"status": "PAID"
}
],
"installments": 1,
"lastUpdate": "2026-06-23T12:00:03.000Z",
"message": "Pagamento aprovado",
"paymentMethod": "CREDIT_CARD",
"paymentMethodId": "payment_method_id",
"previousData": {
"status": "PROCESSING"
},
"productId": "product_id",
"status": "PAID",
"subscriptionId": "subscription_id",
"metadata": {
"externalId": "pedido-123"
}
}
}
```
### Campos de `transaction`
| Campo | Tipo | Descrição |
| --------------------- | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `_id` | `string` | Identificador da transação. |
| `acquirer` | `object` | Dados do adquirente. O payload pode conter `id`, `integrationId`, `name`, `tid`, `chargeId`, `authorization`, `orderId` e `paymentId`, conforme o fluxo e a adquirente. |
| `amount` | `object` | Valor da transação: `currency` e `value`. |
| `boleto` | `object` ou `null` | Dados de boleto: `barcode`, `dueDate`, `url` e `links`. |
| `card` | `object` ou `null` | Dados do cartão, quando salvos no payload interno. Esses dados foram omitidos dos exemplos por não serem necessários para integração via webhook. |
| `chargeId` | `string` | Identificador da cobrança vinculada, quando houver. |
| `clientId` | `string` | Identificador do cliente vinculado. |
| `code` | `string` ou `null` | Código retornado pelo fluxo de pagamento, quando houver. |
| `companyId` | `string` | Identificador da empresa. |
| `createdAt` | `string` | Data de criação em formato ISO. |
| `feeDetails` | `object` ou `null` | Detalhes de taxas, quando houver. |
| `fees` | `number` ou `null` | Valor de taxas, quando houver. |
| `history` | `array` | Histórico da transação. Cada item pode conter `code`, `date`, `message`, `status`, `user`, `integrationId`, `brand` e `acquirer`. |
| `installments` | `number` ou `object` | Parcelamento da transação. |
| `lastUpdate` | `string` | Data da última atualização em formato ISO. |
| `message` | `string` | Mensagem principal do processamento, quando houver. |
| `message2` | `string` | Mensagem complementar do processamento, quando houver. |
| `paymentMethod` | `string` | Método de pagamento usado na transação. |
| `paymentMethodId` | `string` | Identificador do meio de pagamento. |
| `paymentMethodOption` | `array` ou `null` | Opções de método de pagamento, quando houver. |
| `previousData` | `object` ou `null` | Estado anterior da transação. Hoje contém `status`. |
| `productId` | `string` | Identificador do produto vinculado. |
| `qrCode` | `object` ou `null` | Dados de Pix: `text` e `links`. |
| `status` | `string` | Status atual da transação. |
| `subscriptionId` | `string` | Identificador da assinatura vinculada, quando houver. |
| `affiliateId` | `string` | Identificador do afiliado, quando houver. |
| `metadata` | `object` | Metadados enviados na criação ou salvos na transação. |
| `subscription` | `object` | Enviado em `transaction.created` quando a assinatura está disponível no fluxo. |
| `product` | `object` | Enviado em `transaction.created` quando o produto está disponível no fluxo. |
| `client` | `object` | Enviado em `transaction.created` quando o cliente está disponível no fluxo. |
## Subscription webhook
```json theme={null}
{
"type": "subscription.created",
"subscription": {
"_id": "subscription_id",
"active": true,
"canceledDate": null,
"clientId": "client_id",
"companyId": "company_id",
"createdAt": "2026-06-23T12:00:00.000Z",
"history": [
{
"date": "2026-06-23T11:59:55.000Z",
"message": "Assinatura criada",
"status": "CREATED"
}
],
"installments": 1,
"lastUpdate": "2026-06-23T12:00:00.000Z",
"metadata": {
"externalId": "assinatura-123"
},
"nextCharge": "2026-07-23T12:00:00.000Z",
"origin": "API",
"paymentMethod": ["CREDIT_CARD"],
"previousData": null,
"productId": "product_id",
"client": {
"_id": "client_id",
"active": true,
"address": {
"additionalDetails": null,
"city": "São Paulo",
"complement": "Apto 101",
"country": "BR",
"neighborhood": "Centro",
"number": "123",
"state": "SP",
"street": "Rua Exemplo",
"zipcode": "01001000"
},
"birth": "1990-01-01",
"charges": null,
"companyId": "company_id",
"cpf": "12345678909",
"createdAt": "2026-06-23T12:00:00.000Z",
"deleted": null,
"device": null,
"doc": "12345678909",
"email": "cliente@exemplo.com",
"gender": null,
"ipAddress": "127.0.0.1",
"lastUpdate": "2026-06-23T12:00:00.000Z",
"name": "Cliente Veepag",
"note": null,
"phone": ["11999999999"],
"referenceId": "cliente-123",
"status": "ACTIVE",
"type": "INDIVIDUAL"
},
"product": {
"_id": "product_id",
"active": true,
"charge": {
"amount": 9900
},
"checkout": null,
"companyId": "company_id",
"createdAt": "2026-06-23T12:00:00.000Z",
"deleted": false,
"discount": null,
"notification": null,
"product": {
"title": "Seguro Meu+ Residencial",
"price": 99.9
},
"send": null,
"setting": {},
"split": {},
"unsubscription": null
},
"referenceId": "referencia-do-cliente",
"status": "CREATED",
"affiliateId": "affiliate_id",
"checkoutUrl": "https://checkout.veepag.com/..."
}
}
```
O evento `subscription.update` usa a mesma estrutura, alterando apenas o `type` para `subscription.update` e refletindo os dados atualizados da assinatura.
Nos eventos de assinatura, os objetos `client` e `product` são enviados dentro de `subscription` quando disponíveis. O objeto `client` traz os dados cadastrais do cliente, incluindo nome, e-mail, documento, telefones e endereço quando cadastrados. O nome comercial do plano fica em `subscription.product.product.title`. O preço do produto fica em `subscription.product.product.price` e segue o formato cadastrado no produto.
### Campos de `subscription`
| Campo | Tipo | Descrição |
| --------------- | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `_id` | `string` | Identificador da assinatura. |
| `active` | `boolean` | Indica se a assinatura está ativa. |
| `canceledDate` | `string` ou `null` | Data de cancelamento, quando houver. |
| `clientId` | `string` | Identificador do cliente assinante. |
| `companyId` | `string` | Identificador da empresa. |
| `createdAt` | `string` | Data de criação em formato ISO. |
| `history` | `array` | Histórico da assinatura. Cada item pode conter `acquirer`, `brand`, `code`, `date`, `integrationId`, `message`, `status` e `user`. |
| `installments` | `number` | Quantidade de parcelas configurada. |
| `lastUpdate` | `string` | Data da última atualização em formato ISO. |
| `metadata` | `object` | Metadados livres vinculados à assinatura. |
| `nextCharge` | `string` ou `null` | Próxima data de cobrança, quando houver. |
| `origin` | `string` | Origem da criação da assinatura. |
| `paymentMethod` | `array` | Métodos de pagamento disponíveis para a assinatura. |
| `previousData` | `object` ou `null` | Dados anteriores da assinatura. Pode conter `nextCharge` e `status`. |
| `productId` | `string` | Identificador do produto vinculado. |
| `client` | `object` | Cliente vinculado enviado quando disponível no fluxo. |
| `product` | `object` | Produto vinculado enviado quando disponível no fluxo. O nome comercial fica em `product.product.title` e o preço fica em `product.product.price`, no formato cadastrado no produto. |
| `referenceId` | `string` ou `null` | Referência externa enviada pela integração, quando houver. |
| `status` | `string` | Status atual da assinatura. |
| `affiliateId` | `string` | Identificador do afiliado, quando houver. |
| `checkoutUrl` | `string` | URL de checkout, quando houver. |
## Charge webhook
```json theme={null}
{
"type": "charge.update",
"charge": {
"_id": "charge_id",
"active": true,
"amount": {
"value": 9900,
"currency": "BRL"
},
"cardAuth": true,
"clientId": "client_id",
"companyId": "company_id",
"productId": "product_id",
"subscriptionId": "subscription_id",
"description": "Cobrança da assinatura",
"history": [
{
"status": "PAID",
"amount": 9900,
"message": "Pagamento aprovado",
"date": "2026-06-23T12:00:03.000Z"
}
],
"installments": {
"qty": 1,
"installment": 9900,
"type": "NO_INTEREST"
},
"paymentMethod": ["CREDIT_CARD"],
"paymentMethodOption": [
{
"type": "CREDIT_CARD",
"active": true,
"installments": []
}
],
"status": "PAID",
"previousData": {
"status": "PENDING_PAYMENT",
"chargeDate": "2026-06-23T12:00:00.000Z"
},
"number": 1,
"dueDate": "2026-06-23T12:00:00.000Z",
"lastUpdate": "2026-06-23T12:00:03.000Z",
"chargeDate": "2026-06-23T12:00:00.000Z",
"createdAt": "2026-06-23T12:00:00.000Z",
"client": {
"_id": "client_id",
"active": true,
"address": {
"additionalDetails": null,
"city": "São Paulo",
"complement": "Apto 101",
"country": "BR",
"neighborhood": "Centro",
"number": "123",
"state": "SP",
"street": "Rua Exemplo",
"zipcode": "01001000"
},
"birth": "1990-01-01",
"charges": null,
"companyId": "company_id",
"cpf": "12345678909",
"createdAt": "2026-06-23T12:00:00.000Z",
"deleted": null,
"device": null,
"doc": "12345678909",
"email": "cliente@exemplo.com",
"gender": null,
"ipAddress": "127.0.0.1",
"lastUpdate": "2026-06-23T12:00:00.000Z",
"name": "Cliente Veepag",
"note": null,
"phone": ["11999999999"],
"referenceId": "cliente-123",
"status": "ACTIVE",
"type": "INDIVIDUAL"
},
"product": {
"_id": "product_id",
"active": true,
"charge": {
"amount": 9900
},
"checkout": null,
"companyId": "company_id",
"createdAt": "2026-06-23T12:00:00.000Z",
"deleted": false,
"discount": null,
"notification": null,
"product": {
"title": "Plano Proteção Residencial",
"price": 99.9
},
"send": null,
"setting": {},
"split": {},
"unsubscription": null
}
}
}
```
O evento `charge.created` usa a mesma estrutura, alterando apenas o `type` para `charge.created` e refletindo os dados da cobrança criada.
Nos eventos de cobrança, os objetos `client` e `product` são enviados dentro de `charge` quando disponíveis. O objeto `client` traz os dados cadastrais do cliente, incluindo nome, e-mail e documento quando cadastrados.
### Campos de `charge`
| Campo | Tipo | Descrição |
| --------------------- | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `_id` | `string` | Identificador da cobrança. |
| `active` | `boolean` | Indica se a cobrança está ativa. |
| `amount` | `object` | Valor da cobrança: `value` e `currency`. |
| `card` | `object` ou `null` | Resultado de cartão, quando salvo no payload interno. Esses dados foram omitidos dos exemplos por não serem necessários para integração via webhook. |
| `cardAuth` | `boolean` ou `null` | Indica se a cobrança usa autorização de cartão. |
| `clientId` | `string` | Identificador do cliente. |
| `companyId` | `string` | Identificador da empresa. |
| `productId` | `string` | Identificador do produto. |
| `subscriptionId` | `string` ou `null` | Identificador da assinatura vinculada, quando houver. |
| `description` | `string` ou `null` | Descrição da cobrança. |
| `history` | `array` | Histórico da cobrança. Cada item pode conter `status`, `amount`, `message`, `date` e `user`. |
| `installments` | `object` ou `null` | Parcelamento: `qty`, `installment` e `type`. |
| `paymentMethod` | `array` ou `null` | Métodos de pagamento disponíveis para a cobrança. |
| `paymentMethodOption` | `array` ou `null` | Opções de pagamento, com `type`, `active` e `installments`. |
| `status` | `string` | Status atual da cobrança. |
| `previousData` | `object` ou `null` | Dados anteriores da cobrança. Hoje pode conter `status` e `chargeDate`. |
| `number` | `number` | Número sequencial da cobrança, quando houver. |
| `dueDate` | `string` | Data de vencimento em formato ISO. |
| `lastUpdate` | `string` | Data da última atualização em formato ISO. |
| `chargeDate` | `string` ou `null` | Data de cobrança, quando houver. |
| `createdAt` | `string` | Data de criação em formato ISO. |
| `client` | `object` | Cliente vinculado enviado quando disponível. |
| `product` | `object` | Produto vinculado enviado quando disponível. |
## Objetos relacionados
### `client`
O objeto `client` é enviado dentro de `transaction.created` quando o cliente está disponível no fluxo de criação, dentro dos webhooks de assinatura quando disponível e dentro dos webhooks de cobrança quando disponível.
| Campo | Tipo | Descrição |
| ------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `_id` | `string` | Identificador do cliente. |
| `active` | `boolean` | Indica se o cliente está ativo. |
| `address` | `object` ou `null` | Endereço: `additionalDetails`, `city`, `complement`, `country`, `neighborhood`, `number`, `state`, `street` e `zipcode`. |
| `birth` | `string` ou `null` | Data de nascimento, quando houver. |
| `charges` | `object` ou `null` | Informações de cobranças associadas, quando houver. |
| `companyId` | `string` | Identificador da empresa. |
| `cpf` | `string` ou `null` | CPF, quando houver. |
| `createdAt` | `string` | Data de criação em formato ISO. |
| `deleted` | `boolean` ou `null` | Indica exclusão lógica, quando preenchido. |
| `device` | `object` ou `null` | Dados do dispositivo: `colorDepth`, `javaEnable`, `language`, `screenHeight`, `screenWidth`, `timezoneOffset`, `userAgent` e `javaEnabled`. |
| `doc` | `string` ou `null` | Documento do cliente. |
| `email` | `string` ou `null` | E-mail do cliente. |
| `gender` | `string` ou `null` | Gênero, quando houver. |
| `ipAddress` | `string` ou `null` | IP do cliente, quando houver. |
| `lastUpdate` | `string` ou `null` | Data da última atualização em formato ISO. |
| `name` | `string` ou `null` | Nome do cliente. |
| `note` | `string` ou `null` | Observação interna, quando houver. |
| `phone` | `array` ou `null` | Telefones do cliente. |
| `referenceId` | `any` | Referência externa, quando houver. |
| `status` | `string` ou `null` | Status do cliente. |
| `type` | `string` ou `null` | Tipo do cliente. |
### `product`
O objeto `product` é enviado dentro de `transaction.created`, dos webhooks de assinatura e dos webhooks de cobrança quando disponível.
| Campo | Tipo | Descrição |
| ---------------- | ------------------ | --------------------------------------------- |
| `_id` | `string` | Identificador do produto. |
| `active` | `boolean` | Indica se o produto está ativo. |
| `charge` | `object` | Configurações de cobrança do produto. |
| `checkout` | `object` ou `null` | Configurações de checkout, quando houver. |
| `companyId` | `string` | Identificador da empresa. |
| `createdAt` | `string` ou `null` | Data de criação em formato ISO. |
| `deleted` | `boolean` | Indica exclusão lógica. |
| `discount` | `object` ou `null` | Configurações de desconto, quando houver. |
| `notification` | `object` ou `null` | Configurações de notificação, quando houver. |
| `product` | `object` | Dados comerciais do produto. |
| `send` | `object` ou `null` | Configurações de envio, quando houver. |
| `setting` | `object` | Configurações gerais do produto. |
| `split` | `object` | Configuração de split, quando houver. |
| `unsubscription` | `object` ou `null` | Configurações de cancelamento, quando houver. |
## Boas práticas
* Responda rapidamente com status `2xx` quando receber o evento.
* Registre o `type` e o identificador do recurso recebido.
* Trate eventos de forma idempotente sempre que possível.
* Consulte a API quando precisar confirmar o estado final de um recurso.
O provider atual envia um POST JSON simples para a URL configurada. Não há assinatura HMAC, verificação de webhook ou política de retry implementada nesse envio; erros de entrega são logados.
Se você estiver configurando webhooks pela primeira vez, recomendamos começar pelo sandbox e registrar os payloads recebidos. Isso facilita validar o fluxo com calma antes da homologação.