Saltar al contenido
Fipeo

Fipeo para desarrolladores

Webhooks

Acceso anticipado. La API, los webhooks y el widget están apagados para la mayoría de las cuentas mientras los probamos con las primeras escuelas y agencias. Esta documentación es pública para que puedas planear tu integración: escríbenos a [email protected] y te lo encendemos.

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

  1. En Integraciones › Webhooks, pon la dirección de tu servidor y elige los eventos. Puedes tener hasta 10 webhooks.
  2. 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.
  3. 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

EventoParaCuándo
booking.createdagencias y escuelasUna reserva llega a la bandeja de la escuela (la agencia lo recibe de sus propias reservas).
booking.status_changedagencias y escuelasUna reserva cambia de estado: pendiente, otra propuesta, aceptada, rechazada, cancelada, caducada.
message.createdagencias y escuelasUn mensaje nuevo en una conversación: a la agencia cuando escribe la escuela, a la escuela cuando escribe la otra parte.
quote.acceptedagenciasUn estudiante acepta una opción de un presupuesto (se crea la reserva o la solicitud).
student.createdagenciasSe 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.runagenciasUna automatización del CRM ejecuta su acción «webhook» (la dirección tiene que ser uno de tus webhooks activos).
pingagencias y escuelasMandar 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:

http
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

quote.accepted
"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"
} }
student.created
"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"
} }
message.created
"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:

  1. Coge el cuerpo tal cual llegó, antes de interpretarlo (un JSON vuelto a escribir da otra firma).
  2. Calcula el HMAC con tu secreto y compáralo con v1 en tiempo constante.
  3. Rechaza t de más de 5 minutos de diferencia con tu reloj, para que no se pueda repetir una entrega antigua.
PHP
<?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);
}
Node.js
// 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);
Python
# 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 "", 204

Respuesta, reintentos y duplicados

  • Contesta cualquier 2xx en 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 id del evento (X-Fipeo-Event-Id) y lleva un X-Fipeo-Delivery nuevo.
  • Los eventos pueden llegar más de una vez o desordenados: guarda el id de los que ya procesaste y salta los repetidos, y usa created_at para ordenarlos.
  • Las entregas salen de los servidores de Fipeo con User-Agent: Fipeo-Webhooks/1.0. Lo que contesta tu servidor no se guarda.