Webhooks

Neste guia, veremos como registrar e consumir webhooks para integrar seu aplicativo com o Upag. Com os webhooks, seu aplicativo pode ser notificado quando algo acontecer no Upag, como quando um pedido é criado, pago, está pendente, falhou, foi cancelado, ou quando um carrinho é abandonado.

Registrando webhooks

Para registrar um novo webhook, você precisa ter uma URL no seu aplicativo que o Upag possa chamar. Você pode configurar um novo webhook no painel do Upag em Integrações. Dê um nome ao seu webhook, selecione os eventos que deseja escutar e adicione sua URL.

Agora, sempre que algo relevante ocorrer no seu aplicativo, um webhook será disparado pelo Upag. Na próxima seção, veremos como consumir webhooks.

Consumindo webhooks

Quando seu aplicativo recebe uma solicitação de webhook do Upag, verifique o atributo event para identificar qual evento a causou. A primeira parte do tipo de evento indicará o tipo de payload, por exemplo, um pedido, carrinho, etc.

{
  "event": "order.paid",
  "data": {
    "id": "or_9xsS41F8XtXRiUPh",
    "status": "paid",
    "payment_method": "card",
    "currency": "brl",
    // ...
  }
}

No exemplo acima, uma venda foi paga, e o tipo de payload é uma order.paid.

Tipos de Eventos

{
 "event": "order.paid",
 "data": {
   "id": "or_9xsS41F8XtXRiUPh",
   "status": "paid",
   "payment_method": "card",
   "currency": "brl",
   "commission": 415,
   "paid_amount": 1045,
   "product_amount": 1000,
   "shipping_amount": 0,
   "discount": 0,
   "installments": 2,
   "customer": {
     "id": "cus_ahwDXrgYvur89iPs",
     "name": "Teste",
     "email": "teste@upsurge.com.br",
     "phone": "",
     "tax_id": "12345678909",
     "tax_id_type": "cpf",
     "language": "pt-BR"
   },
   "product": {
     "id": "prod_Naa5NFeco9rGjxq6",
     "name": "Upsurge",
     "description": "saas",
     "image": "https://files.upag.io/files/a880a36b-361a-49ff-8121-a374ede8bf0c.png",
     "offer": {
       "id": "of_ACT8Xx6nptY27ZJj",
       "sku": "3264FFOD",
       "description": null,
       "quantity": 1,
       "weight": null,
       "width": null,
       "height": null,
       "length": null
     }
   },
   "billing_address": null,
   "shipping_address": null,
   "shipping_method": null,
   "tracking": {
     "utm_source": "FB",
     "utm_medium": "conjunto",
     "utm_campaign": "campanha",
     "utm_term": "placement",
     "utm_content": "criativo",
     "src": "vsl1",
     "sck": "any",
     "click_id": "123456789"
   }
 }
}

Segurança

Para ter certeza de que um webhook foi realmente enviado pelo Upag e não por um ator malicioso, você pode verificar a assinatura da solicitação. Cada solicitação de webhook contém um cabeçalho chamado signature, e você pode verificar essa assinatura usando sua chave secreta de webhook. A assinatura é um hash HMAC do payload da solicitação, calculado usando sua chave secreta. Aqui está um exemplo de como verificar a assinatura no seu aplicativo:

const signature = req.headers['signature']
const hash = crypto.createHmac('sha256', secret).update(payload).digest('hex')

if (hash === signature) {
  // Request is verified
} else {
  // Request could not be verified
}

If your generated signature matches the x-Upag-signature header, you can be sure that the request was truly coming from Upag. It's essential to keep your secret webhook key safe — otherwise, you can no longer be sure that a given webhook was sent by Upag. Don't commit your secret webhook key to GitHub!