Vai al contenuto
Fipeo

Fipeo for developers

Webhooks

Early access. The API, the webhooks and the widget are switched off for most accounts while we try them with the first schools and agencies. This documentation is public so you can plan your integration: write to [email protected] and we switch it on for you.

A webhook is a POST that Fipeo sends to your server when something happens. Use it to update your systems without asking the API every few minutes.

Set up a webhook

  1. In Integrations › Webhooks, enter the address of your endpoint and choose the events. You can have up to 10 webhooks.
  2. Copy the signing secret (whsec_…): it is shown only once. New secret gives you another one; the old one stops working with the next delivery.
  3. Press Send a test: your endpoint receives a ping event.

The address must be https://, public (no private, local or reserved IP address), on port 443 or 8443, without a user, password or #fragment, and up to 500 characters. Fipeo follows up to 5 redirects and checks each of them again.

Events

EventForWhen
booking.createdagencies and schoolsA booking reaches the school’s inbox (the agency gets it for its own bookings).
booking.status_changedagencies and schoolsA booking changes status: pending, alternative proposed, accepted, declined, cancelled, expired.
message.createdagencies and schoolsA new message in a conversation: to the agency when the school writes, to the school when the other side writes.
quote.acceptedagenciesA student accepts an option of a quote (the booking or booking request is created).
student.createdagenciesA student is added to the CRM by hand in the panel, by one of your forms or by the API (imports from a file do not send it).
automation.runagenciesAn automation of the CRM runs its «webhook» action (the address must be one of your active webhooks).
pingagencies and schoolsSend a test in the panel.

Booking and message events are «thin»: the reference, the status and the school, without the student’s details or the text of the message. Read the rest with the API and your key.

What you receive

Every event is a JSON object, the same for all events, that works as it is in Webhooks by Zapier › Catch Hook and in the Custom webhook of 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"
    }
  }
}

The data of the other events

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"
} }

The exact schema of each event is in the reference. Booking statuses are the same as in the API: new, pending, alternative_proposed, accepted, declined, cancelled, expired; dates and times are ISO 8601 in UTC, as created_at.

Verify the signature

Every delivery is signed. The header is X-Fipeo-Signature: t=<unix seconds>,v1=<signature>, where the signature is the hex HMAC-SHA256 of t + "." + body, with your whole secret (including whsec_) as the key. To check it:

  1. Take the raw body as it arrived, before parsing it (a re-serialised JSON gives another signature).
  2. Compute the HMAC with your secret and compare it with v1 in constant time.
  3. Reject t more than 5 minutes away from your clock, so an old delivery cannot be replayed.
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

Answer, retries and duplicates

  • Answer any 2xx within 10 seconds. Do the slow work afterwards (queue it).
  • Otherwise Fipeo retries after 1, 5 and 15 minutes, 1, 4, 12 and 24 hours: 8 attempts in about 41 hours. Then the delivery is marked Failed.
  • After 20 failed deliveries in a row the webhook switches itself off. Fix your endpoint and switch it on again in the panel.
  • The Deliveries list shows every attempt (status, attempts, response code, error) and lets you Resend one. A resend keeps the same event id (X-Fipeo-Event-Id) and has a new X-Fipeo-Delivery.
  • Events can arrive more than once or out of order: store the id of the events you processed and skip repeats, and use created_at to order them.
  • Deliveries come from Fipeo’s servers with User-Agent: Fipeo-Webhooks/1.0. The answer of your server is not stored.