Recibir notificaciones en tiempo real con webhooks

Para que sirve: Los webhooks permiten que Cargoffer te avise cuando pasa algo importante: un contrato firmado, un pago recibido, una entrega completada. Asi no tienes que estar preguntando constantemente.

El problema

Imagina que necesitas saber cuando se firma un contrato para empezar a preparar el envio. Sin webhooks, tendrias que preguntar cada 5 minutos "se firmo ya?". Con webhooks, nosotros te avisamos en el momento exacto.

Como funciona

1. Tu nos dices una URL donde recibir avisos
2. Nos dices que eventos te interesan
3. Cuando ocurre uno de esos eventos, te enviamos una peticion HTTP a esa URL

Registrar un webhook

curl -X POST "https://api.pro.cargoffer.com/api/webhook" \
  -H "Authorization: Bearer *** \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://tu-sistema.com/webhook",
    "events": ["contract.signed", "payment.received"]
  }'

La URL debe ser publica y accesible desde internet. No vale localhost ni una IP privada.

Eventos disponibles

Evento	Cuando ocurre	Que incluye
auction.created	Creas una subasta	serviceCode, origen, destino
auction.bid	Un transportista oferta	serviceCode, importe
contract.signed	Se firma un contrato	serviceCode, importe, cliente
payment.received	Recibes un pago	invoiceId, importe
delivery.completed	Entrega realizada	deliveryId, fecha

Que recibes

Cuando ocurre un evento, te enviamos algo como esto:

{
  "event": "contract.signed",
  "data": {
    "serviceCode": "SRV-2026-001",
    "amount": 1250.00,
    "timestamp": "2026-06-17T10:00:00Z"
  }
}

Verificar que el webhook es nuestro (seguridad)

Siempre verifica la firma para asegurarte de que el aviso viene realmente de Cargoffer:

import hmac, hashlib

SECRET = "tu_secreto_compartido"

def verificar_webhook(payload, firma):
    esperada = hmac.new(
        SECRET.encode(), payload, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(esperada, firma)

En la practica

1. Crea un endpoint en tu servidor que reciba POST
2. Registra ese endpoint como webhook en Cargoffer
3. Cuando recibas un aviso, procesalo (crea factura, actualiza estado, etc.)
4. Responde con 200 OK para confirmar recepcion

Tip: Si tu endpoint tarda mas de 5 segundos en responder, reintentaremos el envio hasta 3 veces.