Webhooks avisam o ERP/POS sobre alterações relevantes sem ser necessário consultar a API continuamente. A subscrição é configurada em API & Integrações, por ligação e por restaurante.
- Crie ou abra uma ligação no painel do gestor.
- Indique uma URL HTTPS pública e selecione os eventos pretendidos.
- Guarde o identificador do evento recebido para ignorar repetições.
- Valide a assinatura do corpo bruto antes de processar o JSON.
- Responda com HTTP 2xx rapidamente e processe tarefas pesadas numa fila.
Cabeçalhos enviados
POST https://partner.example/webhooks/ngolabooking
Content-Type: application/json
X-NGola-Event-Id: evt_01:connection_01
X-NGola-Event-Type: payment.completed
X-NGola-Timestamp: 2026-09-26T10:30:00.000Z
X-NGola-Signature: sha256=…Envelope de evento
{
"id": "evt_01",
"type": "payment.completed",
"version": "v1",
"occurredAt": "2026-09-26T10:30:00.000Z",
"restaurantId": "rst_01",
"data": {
"paymentId": "pay_01", "reference": "PAY-1201",
"method": "MULTICAIXA_EXPRESS", "amount": 5000
}
}Eventos disponíveis
| Evento | Dados em data | Quando acontece |
|---|---|---|
| booking.confirmed | bookingId, reference, guestCount | Reserva confirmada. |
| booking.checked_in | bookingId, reference | Cliente faz check-in. |
| booking.checked_out | bookingId, reference | Cliente faz check-out. |
| order.paid | orderId, reference, amount | Pedido pago. |
| order.collected | orderId, reference | Takeaway recolhido. |
| payment.completed | paymentId, reference, method, amount | Pagamento confirmado. |
| ticket.paid | eventId, paymentId, reference, ticketCount | Bilhetes de evento pagos. |
| ticket.checked_in | ticketId, eventId | Bilhete validado na entrada. |
Validar assinatura
A assinatura é HMAC-SHA256 de timestamp + "." + rawBody. A chave é o hash SHA-256 do segredo da ligação. Preserve o corpo bruto: reserializar o JSON pode alterar a assinatura.
const signingKey = sha256(process.env.NGOLA_INTEGRATION_SECRET);
const expected = hmacSha256(signingKey, timestamp + "." + rawBody);
const received = signature.replace("sha256=", "");
const valid = timingSafeEqual(expected, received);Cada entrega tem um limite de 10 segundos. Em caso de falha, a plataforma tenta entregar até cinco vezes. Uma ligação pausada ou revogada deixa de receber eventos.