Webhooks

How they work

SES Hospedajes processes reports asynchronously: the nightly submission gets a batch number and the confirmation (or the rejection) arrives on a later query. Instead of making you poll GET /checkins/{reservationId}/ses, configure a webhook and Kinapi will POST to your URL on every event. You set it up in the panel: Settings → Webhooks (URL, signing secret and which events you subscribe to).

Events

Delivery format

A JSON body with a fixed shape: { event, timestamp, livemode, data }. livemode is false for events from test mode, where nothing reaches the Ministry: if one receiver serves both environments, drop or route by that field. What is inside data depends on the event; booking and report events include reservationId and listingId so you can tie them back to your system, and export events carry exportId (see Exports and offboarding).

{
  "event": "guest.registered",
  "timestamp": "2026-08-14T18:03:11.000Z",
  "livemode": true,
  "data": {
    "reservationId": "R-2026-0412",
    "listingId": "38291",
    "guestId": "5f0c33f1-…",
    "name": "María García López",
    "isLead": true,
    "registered": 3,
    "expected": 4,
    "status": "in_progress",
    "source": "guest"
  }
}

registered and expected are recounted at send time rather than derived from what was there before: two guests in the same party can be submitting the form from their phones at the same moment. source tells you whether the registration came from the guest form or from your own API call.

{
  "event": "ses.confirmed",
  "timestamp": "2026-08-15T07:30:12.000Z",
  "livemode": true,
  "data": {
    "reservationId": "R-2026-0412",
    "listingId": "38291",
    "lote": "20260815-000123",
    "comunicaciones": [
      {
        "guestName": "María García López",
        "codigoComunicacion": "SES-2026-…",
        "errores": []
      }
    ]
  }
}

{
  "event": "ses.error",
  "timestamp": "2026-08-15T07:30:12.000Z",
  "livemode": true,
  "data": {
    "reservationId": "R-2026-0412",
    "listingId": "38291",
    "phase": "poll",
    "reason": "María García López: documento caducado",
    "lote": "20260815-000123",
    "comunicaciones": [ … ]
  }
}

{
  "event": "ses.cancel_failed",
  "timestamp": "2026-08-16T11:30:08.000Z",
  "livemode": true,
  "data": {
    "reservationId": "R-2026-0412",
    "listingId": "38291",
    "phase": "processing",
    "lote": "20260816-000045",
    "reason": "…the Ministry’s reason, verbatim…"
  }
}

{
  "event": "export.ready",
  "timestamp": "2026-10-14T09:03:12.000Z",
  "livemode": true,
  "data": {
    "exportId": "3f6c1e2a-…",
    "description": "Propietario Gestora Costa SL",
    "bookings": 412,
    "bytes": 184503112,
    "expiresAt": "2026-10-21T09:03:12.000Z"
  }
}

Verifying the signature

Every delivery carries the X-Kinapi-Signature-SHA256 header: the HMAC-SHA256 (hex) of the raw body, computed with the signing secret you can see in the panel. Recompute it and discard any request that does not match — that way nobody can inject fake events into your endpoint. The X-Kinapi-Event header carries the event name, and X-Kinapi-Livemode repeats livemode (true or false) so you can decide without reading the body.

import { createHmac, timingSafeEqual } from 'node:crypto';

app.post('/webhooks/kinapi', express.raw({ type: 'application/json' }), (req, res) => {
  const expected = createHmac('sha256', process.env.KINAPI_WEBHOOK_SECRET)
    .update(req.body) // the RAW body, unparsed
    .digest('hex');
  const received = req.get('X-Kinapi-Signature-SHA256') ?? '';
  const valid =
    received.length === expected.length &&
    timingSafeEqual(Buffer.from(received), Buffer.from(expected));
  if (!valid) return res.status(401).end();

  const { event, data } = JSON.parse(req.body);
  // process and answer quickly — any 2xx counts as delivered
  res.status(200).end();
});

Retries and idempotency

If your endpoint does not answer 2xx, Kinapi retries up to 3 times (immediately, ~2 s and ~10 s later) with a 10 s timeout per attempt. Delivery is at least once: on a timeout just after you processed it, you could receive the same event twice — make your processing idempotent using event + data.reservationId (or data.exportId) + timestamp as the deduplication key.

Every attempt is logged in the panel (Settings → Webhooks) with its outcome, its duration and the exact body sent — the log is kept for 30 days.

Resending a failed delivery

If a delivery exhausts its three attempts, a Resend button appears next to it in the panel’s log. It sends the same body, with its original timestamp untouched so your deduplication keeps working, but to the current URL and signed with the current secret: if the failure came from a wrong URL or a half-rotated secret, resending to the old destination would fail the same way. The request carries an X-Kinapi-Redelivery header with the original delivery’s id, in case you want to tell it apart in your logs.

It is a single attempt, without the retry ladder: a person triggers it while looking at the log, and there is no point making them wait.