Webhooks
Recibe notificaciones en tiempo real cuando ocurren eventos en WardOps. Los webhooks te permiten integrar tu sistema para reaccionar automaticamente a cambios y eventos.
Como funcionan los webhooks
Gestion de Webhooks
Registrar webhook
Registra un nuevo endpoint para recibir webhooks.
Body (JSON)
| Parametro | Tipo | Requerido | Descripcion |
|---|---|---|---|
url | string | Si | URL HTTPS donde recibir los eventosEjemplo: https://yourapp.com/webhooks/wardops |
events | array | Si | Lista de eventos a suscribirEjemplo: ["guard.checkin", "alert.created"] |
description | string | No | Descripcion para identificar el webhookEjemplo: Webhook principal |
secret | string | No | Secret personalizado para firmar los payloads (se generara uno si no se proporciona) |
Ejemplo
curl --request POST \
--url 'https://api.wardops.com/v1/webhooks' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"url": "https://yourapp.com/webhooks/wardops",
"events": ["guard.checkin", "guard.checkout", "alert.created"],
"description": "Notificaciones de check-ins y alertas"
}'Respuestas
{
"data": {
"id": "whk_abc123",
"url": "https://yourapp.com/webhooks/wardops",
"events": ["guard.checkin", "guard.checkout", "alert.created"],
"description": "Notificaciones de check-ins y alertas",
"secret": "whsec_xxxxxxxxxxxxxxxxxxxxx",
"status": "active",
"created_at": "2024-01-25T10:00:00Z"
}
}{
"error": {
"code": "validation_error",
"message": "La URL debe usar HTTPS",
"details": {
"url": ["La URL debe usar el protocolo HTTPS"]
}
}
}Eventos Disponibles
Lista completa de eventos que puedes suscribir en tus webhooks.
{
"event": "guard.checkin",
"timestamp": "2024-01-25T08:02:30Z",
"data": {
"checkin_id": "chk_xyz789",
"guard_id": "grd_123abc",
"guard_name": "Juan Perez",
"assignment_id": "asn_abc123",
"post_name": "Edificio Central",
"location": {
"latitude": 19.4326,
"longitude": -99.1332
},
"is_on_time": true
}
}{
"event": "guard.checkout",
"timestamp": "2024-01-25T20:05:00Z",
"data": {
"checkin_id": "chk_xyz790",
"guard_id": "grd_123abc",
"guard_name": "Juan Perez",
"assignment_id": "asn_abc123",
"total_hours": 12.04
}
}{
"event": "alert.created",
"timestamp": "2024-01-25T14:30:00Z",
"data": {
"alert_id": "alt_abc123",
"type": "geofence_exit",
"severity": "high",
"guard_id": "grd_123abc",
"guard_name": "Juan Perez",
"message": "El guardia salio de la geocerca permitida",
"location": {
"latitude": 19.4400,
"longitude": -99.1400
}
}
}{
"event": "shift.started",
"timestamp": "2024-01-25T08:00:00Z",
"data": {
"assignment_id": "asn_abc123",
"guard_id": "grd_123abc",
"guard_name": "Juan Perez",
"post_id": "pst_789xyz",
"post_name": "Edificio Central",
"scheduled_start": "2024-01-25T08:00:00Z",
"scheduled_end": "2024-01-25T20:00:00Z"
}
}{
"event": "shift.ended",
"timestamp": "2024-01-25T20:00:00Z",
"data": {
"assignment_id": "asn_abc123",
"guard_id": "grd_123abc",
"guard_name": "Juan Perez",
"actual_start": "2024-01-25T08:02:30Z",
"actual_end": "2024-01-25T20:05:00Z",
"total_hours": 12.04,
"overtime_minutes": 5
}
}{
"event": "report.created",
"timestamp": "2024-01-25T14:30:00Z",
"data": {
"report_id": "rpt_abc123",
"type": "incident",
"priority": "high",
"title": "Intento de acceso no autorizado",
"guard_id": "grd_123abc",
"guard_name": "Juan Perez",
"post_name": "Edificio Central",
"has_attachments": true
}
}{
"event": "guard.location_updated",
"timestamp": "2024-01-25T08:15:00Z",
"data": {
"guard_id": "grd_123abc",
"location": {
"latitude": 19.4326,
"longitude": -99.1332,
"accuracy": 10.5
},
"battery_level": 85,
"is_within_geofence": true
}
}| Evento | Descripcion |
|---|---|
guard.checkin | Check-in de guardia |
guard.checkout | Check-out de guardia |
guard.location_updated | Actualizacion de ubicacion |
alert.created | Nueva alerta generada |
shift.started | Inicio de turno |
shift.ended | Fin de turno |
report.created | Nuevo reporte creado |
* | Todos los eventos (wildcard) |
Verificacion de Webhooks
Es importante verificar que los webhooks provienen de WardOps y no han sido manipulados.
WardOps firma cada peticion de webhook usando tu secret y el algoritmo HMAC-SHA256. La firma se incluye en el header X-WardOps-Signature.
Headers incluidos
POST /webhooks/wardops HTTP/1.1
Host: yourapp.com
Content-Type: application/json
X-WardOps-Signature: sha256=5d77a3b5b8c7d6e5f4a3b2c1d0e9f8a7b6c5d4e3f2
X-WardOps-Timestamp: 1706176800
X-WardOps-Event: guard.checkin
X-WardOps-Delivery-Id: dlv_abc123Como verificar la firma
const crypto = require('crypto');
function verifyWebhook(payload, signature, timestamp, secret) {
// Construir el mensaje a verificar
const signedPayload = `${timestamp}.${JSON.stringify(payload)}`;
// Calcular la firma esperada
const expectedSignature = crypto
.createHmac('sha256', secret)
.update(signedPayload)
.digest('hex');
// Comparar firmas de forma segura
const expected = `sha256=${expectedSignature}`;
return crypto.timingSafeEqual(
Buffer.from(signature),
Buffer.from(expected)
);
}
// En tu endpoint
app.post('/webhooks/wardops', (req, res) => {
const signature = req.headers['x-wardops-signature'];
const timestamp = req.headers['x-wardops-timestamp'];
// Verificar que el timestamp no sea muy antiguo (5 minutos)
const now = Math.floor(Date.now() / 1000);
if (now - parseInt(timestamp) > 300) {
return res.status(400).json({ error: 'Timestamp too old' });
}
if (!verifyWebhook(req.body, signature, timestamp, WEBHOOK_SECRET)) {
return res.status(401).json({ error: 'Invalid signature' });
}
// Procesar el evento
const event = req.body;
console.log('Evento recibido:', event.event);
res.status(200).json({ received: true });
});Politica de Reintentos
Si tu endpoint no responde con un codigo 2xx, WardOps reintentara la entrega automaticamente.
| Intento | Tiempo de espera |
|---|---|
| 1 | Inmediato |
| 2 | 1 minuto |
| 3 | 5 minutos |
| 4 | 30 minutos |
| 5 | 2 horas |
Desactivacion automatica
Despues de 5 intentos fallidos consecutivos, el webhook se pausara automaticamente. Recibiras una notificacion por email.
Mejores Practicas
Necesitas ayuda?
Nuestro equipo puede ayudarte a configurar los webhooks correctamente.