Criar webhook

Cria um webhook para o objeto especificado.

POST /webhooks

Requer autenticação. Envie suas credenciais no header Authorization. Veja Autenticação.

Requisição

POST /webhooks
Content-Type: application/json
Authorization: Basic <suas_credenciais_em_base64>

{
  "callback_url": "https://yourdomain.com/webhook",
  "object": "PAYMENT",
  "verify_token": "your-secure-token-min-24-chars"
}

Parâmetros

Prop

Type

Resposta

{
  "id": "a80c22da-2433-4ae5-95a8-f25e30737cb9",
  "callback_url": "https://api.mycompany.com/paggpix-payment-webhook",
  "object": "PAYMENT",
  "created": "2024-08-10T14:43:05.894Z"
}

Campos da resposta

Prop

Type

Fluxo de verificação

No momento da criação, a API inicia um processo de verificação fazendo uma requisição GET para a callback_url para confirmar que a URL é funcional.

Requisição de verificação:

GET https://yourdomain.com/webhook?mode=subscribe&challenge=<random-hex>
X-Verify-Token: <your-verify-token>

mode=subscribe: indica que é uma requisição de verificação
challenge=<random-hex>: número hexadecimal aleatório. Seu servidor deve retorná-lo no corpo da resposta.
X-Verify-Token: token enviado para comparação com o verify_token fornecido

Validação da resposta

Seu servidor deve responder em até 5 segundos com HTTP 2xx e o mesmo challenge no corpo. Qualquer falha (timeout, status não-2xx, token inválido) impedirá a criação do webhook.

Exemplo de verificação (Node.js)

import express from 'express';

const app = express();
const verifyToken = 'your-secure-token-min-24-chars'; // Armazene de forma segura

app.get('/webhook', (req, res) => {
  const verify_token = req.headers['x-verify-token'];
  const { mode, challenge } = req.query;

  if (mode === 'subscribe' && verify_token === verifyToken) {
    res.status(200).send(challenge);
  } else {
    res.status(403).send('Invalid verification token');
  }
});

app.listen(3000);

Solução de problemas

Timeout: a URL de callback demora mais de 5s para responder?
Status HTTP: o servidor responde com 4xx ou 5xx?
Conectividade: a URL de callback está acessível? (DNS, firewall)
Token inválido: o verify_token está sendo comparado corretamente?
Erros internos: há exceções nos logs do servidor?

On this page