Webhooks

Criar Webhook

POST/v1/users/webhooks

Base URL Produção:https://api.validapay.com.br

Base URL Sandbox:https://sandbox.validapay.com.br

Autenticação

bearerAuthorizationstring · header · obrigatório

Envie no header:

Authorization: Bearer {{token}}

Cadastra um endereço para receber avisos automáticos sempre que algo acontecer na sua conta, como um pagamento confirmado ou cancelado.

Registrar webhook

Campo	Obrig.	Tipo	Descrição
`url`	✅	string	Endpoint HTTPS
`events`	❌	string[]	Eventos a escutar (vazio = todos)
`authToken`	❌	string	Header de auth enviado nos disparos

Eventos: charge.created payment.success payment.failed payment.overdue subscription.created subscription.activated subscription.canceled subscription.renewed subscription.trial subscription.upgraded subscription.item_added subscription.downgrade_scheduled onboarding.documentscopy onboarding.proposal onboarding.backgroundcheck onboarding.create refund.requested refund.confirmed refund.failed med.infraction.updated med.balance.blocked med.balance.unblocked med.refund.opened med.refund.closed

Body

application/json

Content-Type:application/json

{
  "url": "https://meusite.com/webhook",
  "events": [
    "charge.created",
    "payment.success",
    "payment.failed",
    "subscription.created",
    "subscription.activated",
    "subscription.canceled",
    "subscription.renewed"
  ],
  "authToken": "meu-token-secreto"
}

Schema

Field	Type	Required	Description
url	string	-	-
events[7]	array	-	-
authToken	string	-	-

Headers

Name	Type	Value	Required
Content-Type	-	application/json	Optional

← Anterior

Consultar Reembolso

Listar Webhooks

const url = 'https://sandbox.validapay.com.br/v1/users/webhooks';

const options = {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer {{token}}',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
  "url": "https://meusite.com/webhook",
  "events": [
    "charge.created",
    "payment.success",
    "payment.failed",
    "subscription.created",
    "subscription.activated",
    "subscription.canceled",
    "subscription.renewed"
  ],
  "authToken": "meu-token-secreto"
})
};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error(err));

Response Examples

201201

{
  "webhookId": "wh_xxx",
  "url": "https://meusite.com/webhook",
  "events": [
    "payment.success"
  ],
  "status": "active",
  "createdAt": "2024-01-15T10:30:00Z"
}

400400

{
  "code": "VALIDATION_ERROR",
  "message": "URL inválida"
}

← Anterior

Consultar Reembolso

Listar Webhooks