Webhooks
Un webhook es un POST que Fipeo manda a tu servidor cuando pasa algo. Úsalo para tener tus sistemas al día sin preguntar a la API cada pocos minutos.
Configura un webhook
- En Integraciones › Webhooks, pon la dirección de tu servidor y elige los eventos. Puedes tener hasta 10 webhooks.
- Copia el secreto de la firma (
whsec_…): solo se enseña una vez. Secreto nuevo te da otro; el anterior deja de valer con la próxima entrega. - Pulsa Mandar una prueba: tu servidor recibe un evento
ping.
La dirección tiene que ser https://, pública (nada de IP privadas, locales ni reservadas), en el puerto 443 u 8443, sin usuario, contraseña ni #fragmento, y de hasta 500 caracteres. Fipeo sigue hasta 5 redirecciones y comprueba cada una otra vez.
Eventos
| Evento | Para | Cuándo |
|---|---|---|
booking.created | agencias y escuelas | Una reserva llega a la bandeja de la escuela (la agencia lo recibe de sus propias reservas). |
booking.status_changed | agencias y escuelas | Una reserva cambia de estado: pendiente, otra propuesta, aceptada, rechazada, cancelada, caducada. |
message.created | agencias y escuelas | Un mensaje nuevo en una conversación: a la agencia cuando escribe la escuela, a la escuela cuando escribe la otra parte. |
quote.accepted | agencias | Un estudiante acepta una opción de un presupuesto (se crea la reserva o la solicitud). |
student.created | agencias | Se añade un estudiante al CRM a mano en el panel, por uno de tus formularios o por la API (las importaciones desde un fichero no lo mandan). |
automation.run | agencias | Una automatización del CRM ejecuta su acción «webhook» (la dirección tiene que ser uno de tus webhooks activos). |
ping | agencias y escuelas | Mandar una prueba en el panel. |
Los eventos de reservas y mensajes son «delgados»: la referencia, el estado y la escuela, sin los datos del estudiante ni el texto del mensaje. El resto se lee con la API y tu clave.
Qué recibes
Cada evento es un objeto JSON, igual para todos, que vale tal cual en Webhooks by Zapier › Catch Hook y en el Custom webhook de Make:
POST https://your-server.example.com/fipeo
Content-Type: application/json
User-Agent: Fipeo-Webhooks/1.0
X-Fipeo-Event: booking.status_changed
X-Fipeo-Event-Id: evt_6f1d0c3e9b2a4d5f8e7c6b5a49382716
X-Fipeo-Delivery: 3b6e…
X-Fipeo-Signature: t=1762858800,v1=5f2b…
{
"id": "evt_6f1d0c3e9b2a4d5f8e7c6b5a49382716",
"type": "booking.status_changed",
"created_at": "2026-11-11T10:00:00Z",
"api_version": "2026-11-09",
"organization": { "type": "agency", "id": "a1111111-1111-4111-8111-111111111111" },
"data": {
"booking": {
"id": "7c2…", "reference": "FA-ABCDEFGHIJ", "status": "accepted", "previous_status": "pending",
"school_id": 1060, "changed_at": "2026-11-11T10:00:00Z"
}
}
}El data de los demás eventos
"data": { "quote": {
"id": "…", "number": "Q-2026-0042", "student_id": "…", "accepted_option": 1,
"school": { "id": 1060, "name": "Omeida Chinese Academy" },
"booking_reference": "FA-ABCDEFGHIJ", "booking_status": "new", "accepted_at": "2026-11-11T10:00:00Z"
} }"data": { "student": {
"id": "…", "owner_id": "…", "first_name": "Lucía", "last_name": "Pérez", "email": "[email protected]", "phone": null,
"nationality": "AR", "language": "es", "study_language": "en", "start_from": "2027-07-05", "weeks": 4,
"source": "website", "tags": ["web"], "consent": true, "created_at": "2026-11-11T10:00:00Z"
} }"data": { "message": {
"id": "…", "conversation_id": "…", "booking_reference": "FA-ABCDEFGHIJ", "subject": "Arrival time",
"school": { "id": 1060, "name": "Omeida Chinese Academy" }, "created_at": "2026-11-11T10:00:00Z", "from": "school"
} }El esquema exacto de cada evento está en la referencia. Los estados de las reservas son los mismos que en la API: new, pending, alternative_proposed, accepted, declined, cancelled, expired; las fechas con hora, en ISO 8601 y UTC, como created_at.
Comprueba la firma
Cada entrega va firmada. La cabecera es X-Fipeo-Signature: t=<segundos unix>,v1=<firma>, donde la firma es el HMAC-SHA256 en hexadecimal de t + "." + cuerpo, con tu secreto entero (con whsec_) como clave. Para comprobarla:
- Coge el cuerpo tal cual llegó, antes de interpretarlo (un JSON vuelto a escribir da otra firma).
- Calcula el HMAC con tu secreto y compáralo con
v1en tiempo constante. - Rechaza
tde más de 5 minutos de diferencia con tu reloj, para que no se pueda repetir una entrega antigua.
<?php
// Verify a Fipeo webhook (X-Fipeo-Signature: t=<unix>,v1=<hex HMAC-SHA256>).
// $secret is the whole webhook secret as shown in the panel, including «whsec_».
function fipeo_signature_is_valid(string $secret, string $header, string $body, ?int $now = null): bool
{
if (1 !== preg_match('/^t=(\d{1,12}),v1=([0-9a-f]{64})$/', $header, $m)) {
return false;
}
if (abs(($now ?? time()) - (int) $m[1]) > 300) {
return false; // older than 5 minutes: maybe a replay
}
$expected = hash_hmac('sha256', $m[1].'.'.$body, $secret);
return hash_equals($expected, $m[2]);
}
// In your endpoint: read the raw body, check, answer 2xx quickly.
if (PHP_SAPI !== 'cli') {
$body = (string) file_get_contents('php://input');
if (!fipeo_signature_is_valid((string) getenv('FIPEO_WEBHOOK_SECRET'), $_SERVER['HTTP_X_FIPEO_SIGNATURE'] ?? '', $body)) {
http_response_code(400);
exit;
}
$event = json_decode($body, true);
// $event['id'] is the same when an event is resent: skip it if you already have it.
http_response_code(204);
}// Verify a Fipeo webhook in Node.js (no dependencies). `secret` is the whole webhook secret, including «whsec_».
import { createHmac, timingSafeEqual } from 'node:crypto';
import { createServer } from 'node:http';
export function fipeoSignatureIsValid(secret, header, rawBody, now = Date.now() / 1000) {
const m = /^t=(\d{1,12}),v1=([0-9a-f]{64})$/.exec(header || '');
if (!m || Math.abs(now - Number(m[1])) > 300) return false; // older than 5 minutes: maybe a replay
const expected = createHmac('sha256', secret).update(`${m[1]}.`).update(rawBody).digest();
return timingSafeEqual(expected, Buffer.from(m[2], 'hex'));
}
// In your endpoint: read the raw body (not a re-serialised JSON), check, answer 2xx quickly.
export function servidor(secret = process.env.FIPEO_WEBHOOK_SECRET) {
return createServer((req, res) => {
const chunks = [];
req.on('data', (c) => chunks.push(c));
req.on('end', () => {
const body = Buffer.concat(chunks);
if (!fipeoSignatureIsValid(secret, req.headers['x-fipeo-signature'], body)) return res.writeHead(400).end();
const event = JSON.parse(body.toString('utf8'));
// event.id is the same when an event is resent: skip it if you already have it.
res.writeHead(204).end();
});
});
}
// servidor().listen(3000);# Verify a Fipeo webhook in Python 3 (standard library only).
# SECRET is the whole webhook secret, including «whsec_».
import hashlib
import hmac
import os
import re
import time
SECRET = os.environ.get("FIPEO_WEBHOOK_SECRET", "")
def fipeo_signature_is_valid(secret: str, header: str, raw_body: bytes, now: float | None = None) -> bool:
m = re.fullmatch(r"t=(\d{1,12}),v1=([0-9a-f]{64})", header or "")
if not m or abs((time.time() if now is None else now) - int(m.group(1))) > 300:
return False # older than 5 minutes: maybe a replay
expected = hmac.new(secret.encode(), m.group(1).encode() + b"." + raw_body, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, m.group(2))
# Flask:
# @app.post("/fipeo")
# def fipeo():
# if not fipeo_signature_is_valid(SECRET, request.headers.get("X-Fipeo-Signature", ""), request.get_data()):
# abort(400)
# event = request.get_json() # event["id"] is the same when an event is resent
# return "", 204Respuesta, reintentos y duplicados
- Contesta cualquier
2xxen menos de 10 segundos. Lo lento, hazlo después (en una cola). - Si no, Fipeo reintenta a los 1, 5 y 15 minutos, y a las 1, 4, 12 y 24 horas: 8 intentos en unas 41 horas. Después la entrega queda Fallida.
- Tras 20 entregas fallidas seguidas el webhook se apaga solo. Arregla tu servidor y vuelve a activarlo en el panel.
- La lista de Entregas enseña cada intento (estado, intentos, código de respuesta, error) y deja Reenviar una. Un reenvío conserva el
iddel evento (X-Fipeo-Event-Id) y lleva unX-Fipeo-Deliverynuevo. - Los eventos pueden llegar más de una vez o desordenados: guarda el
idde los que ya procesaste y salta los repetidos, y usacreated_atpara ordenarlos. - Las entregas salen de los servidores de Fipeo con
User-Agent: Fipeo-Webhooks/1.0. Lo que contesta tu servidor no se guarda.