Webhooks

Webhooks notify your server when a booking or post-booking operation changes. Jinko sends a signed POST when payment starts, a booking completes or fails, or a cancellation or exchange reaches an outcome.

How it works

Register a public HTTPS endpoint and choose the events you need.
Jinko sends a signed event when the booking changes.
Verify the signature and deduplicate the event.
Return 2xx, then process the event in your application.

When Jinko sends a traveler email at the same moment, the event also includes its content in data.customer_emails. See Send your own customer emails to use that data with your own brand.

Prerequisites

A Jinko account
A public HTTPS endpoint that can receive a POST

The /v1/webhooks management endpoints do not accept tenant keys. Register the endpoint on the Webhooks page in the dashboard when you use a tenant key. The API accepts only legacy person-bound keys with the bare jnk_ prefix.

Tenant subscriptions

A booking made with a tenant key sends events to the subscriptions registered for that tenant. The payload, headers, and signature are the same for every authentication mode. Register the endpoint in the dashboard, select the tenant, and choose the events. Subscriptions are environment-specific, so register them separately in production and sandbox. For sandbox bookings, turn on Sandbox mode in the dashboard before creating the subscription.

Register an endpoint

Dashboard
API

Open Webhooks in the dashboard, select Add webhook, paste your URL, choose the events, and select Create. Copy the signing secret shown once. You need it to verify deliveries.

curl -X POST https://api.gojinko.com/v1/webhooks \
  -H "X-API-Key: $JINKO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/jinko",
    "events": ["booking.completed", "booking.partial", "booking.failed"]
  }'

The response contains the signing secret once, so store it securely:

{
  "id": 42,
  "url": "https://your-app.com/webhooks/jinko",
  "events": ["booking.completed", "booking.partial", "booking.failed"],
  "secret": "whsec_3f9a…",
  "status": "active",
  "created_at": "2027-06-02T08:00:00Z"
}

Choose events

Event	`status` (deprecated)	When it fires
`booking.processing`	`processing`	The payment is authorized and the booking is being confirmed with the suppliers. No supplier reference exists yet.
`booking.completed`	`confirmed`	Every item in the trip was booked. A seat can still be pending (see below).
`booking.partial`	`partial`	Some items booked and some failed. Money was captured for the items that booked.
`booking.failed`	`failed`	No item could be booked. The payment hold is released and nothing is charged.
`servicing.completed`	`servicing.completed`	A cancellation of one booked item is complete and its money is settled.
`servicing.exchange_confirmed`	`servicing.exchange_confirmed`	The supplier confirmed an exchange of one booked item. For a flight, the new e-ticket number can follow in `servicing.ticket_issued`.
`servicing.ticket_issued`	`servicing.ticket_issued`	The new e-ticket number of an exchanged flight is available.
`servicing.failed`	`servicing.failed`	An exchange or a refund could not be completed. The original booking is unchanged unless the payload says otherwise.

Seat confirmation: Jinko sends booking.completed and the flight booking confirmation email once the flight is ticketed, even if a seat is still pending. Read booked_ancillaries for each seat’s outcome. See Seat maps. Exactly one of booking.completed, booking.partial and booking.failed fires per trip. They are mutually exclusive. booking.processing reports an earlier moment: the payment is authorized and the booking is being confirmed. The servicing.* events fire after the booking, once for each operation, and only if you subscribe to them.

booking.partial is not a success. If you subscribe to it, treat it as “money moved and the trip is incomplete”, and reconcile per item using the data object below. If you do not subscribe to it, a partially-fulfilled trip sends you nothing at all, and you will only find it by polling get_trip.This is why booking.partial is a distinct event rather than a flag on booking.completed: a consumer that has never heard of it cannot silently mistake a half-booked trip for a confirmed one.

More event types will be added over time. Treat the event field as an open enum and ignore events you don’t handle. No event reports a change the airline makes after ticketing, such as a schedule change or a cancellation. Jinko doesn’t detect those today, and get_booking returns the itinerary as it was booked. Every event in the table is in the WebhookEvent enum of the production OpenAPI contract.

Read the payload

Every event carries these six fields. The example leaves out data, described below:

{
  "event": "booking.completed",
  "booking_ref": "JNK-A7B3X9",
  "status": "confirmed",
  "occurred_at": "2027-06-02T08:00:00Z",
  "event_id": "evt_8d2f41c9a07e",
  "livemode": true
}

Those six fields are on every event and never change. status is deprecated: branch on event, which already names the outcome. Events also carry a data object with the facts of the booking or the operation and, when Jinko emails your traveler at that moment, that email:

Event	`data`
`booking.processing`	`customer_emails` and `manage_booking_url`: see Customer emails.
`booking.completed`	Each booked item with its supplier references (see Completed bookings), and `customer_emails` and `manage_booking_url`.
`booking.partial`	What happened to each item and what was captured: see Partial bookings. No `customer_emails`: Jinko sends no email at that moment.
`booking.failed`	`failure_reason` and `failure_message` (see Failed bookings), and `customer_emails`.
`servicing.completed`	The operation and its money (see Cancellations), and `customer_emails`.
`servicing.exchange_confirmed`, `servicing.ticket_issued`, `servicing.failed`	The operation (see Exchanges and failed operations), and `customer_emails`.

Fetch the full booking with get_booking using the booking_ref.

Customer emails

Every event except booking.partial carries data.customer_emails: one entry for each email Jinko sends, or would send, your traveler at that moment, with what the email shows. Use it to send the email in your own brand. Send your own customer emails explains how, and how to ask Jinko to stop sending its own.

{
  "event": "booking.completed",
  "booking_ref": "JNK-8F3D21",
  "status": "confirmed",
  "occurred_at": "2027-06-02T08:00:00Z",
  "event_id": "evt_e5a09b3c7d12",
  "livemode": true,
  "data": {
    "manage_booking_url": "https://app.gojinko.com/bookings/JNK-8F3D21?ln=Martin",
    "customer_emails": [
      {
        "template": "flight-ticketing-confirmation",
        "to": "jane.martin@example.com",
        "subject": "Your tickets are confirmed: JNK-8F3D21",
        "content": {
          "pnr": "JNK-8F3D21",
          "airline_pnr": "XM9L7Q",
          "destination_city_name": "Paris",
          "passengers": [
            { "first_name": "Jane", "last_name": "Martin", "type": "Adult", "ticket_number": "0167654321098" }
          ]
        }
      },
      {
        "template": "hotel-booking-confirmation",
        "to": "jane.martin@example.com",
        "subject": "Your stay at Hôtel Marais is confirmed",
        "content": {
          "pnr": "JNK-8F3D21",
          "supplier_booking_id": "4412983",
          "hotel": { "name": "Hôtel Marais" },
          "stay": { "duration_label": "3 nights" },
          "guests": [{ "first_name": "Jane", "last_name": "Martin" }]
        },
        "calendar": {
          "files": [
            {
              "method": "REQUEST",
              "filename": "jinko-JNK-8F3D21.ics",
              "content_type": "text/calendar; charset=utf-8; method=REQUEST",
              "content": "BEGIN:VCALENDAR\r\n…"
            }
          ]
        }
      }
    ]
  }
}

Field	Notes
`data.manage_booking_url`	The manage-booking link, when Jinko’s email at that moment carries one. It includes the traveler’s last name.
`data.customer_emails[]`	One entry per email, in sending order. A booking with a flight and a hotel gives two entries. The entries are the same whether Jinko sends its own emails or not.
`customer_emails[].template`	Which email this is, for example `flight-ticketing-confirmation`. It sets the shape of `content`.
`customer_emails[].to`	The address Jinko’s email goes to: the booking contact. Absent when the booking has none.
`customer_emails[].subject`	The subject line of Jinko’s email.
`customer_emails[].content`	The values the email shows, under snake_case keys. Dates, times and amounts are display strings, as the email shows them. Empty values are left out.
`customer_emails[].calendar`	The calendar files the email attaches, in the `{ files: [{ method, filename, content_type, content }] }` shape of the booking read. Present only when the email attaches one.

The example shows only some fields of each content. Each template’s content has its own schema in the OpenAPI contract, named after the template: for example FlightTicketingConfirmationEmailContent. A later version can add fields to content and entries to customer_emails, so ignore what you don’t use.

customer_emails contains traveler personal data: names, email addresses, itineraries and ticket numbers. manage_booking_url contains the traveler’s last name. Treat every payload that carries them as personal data, including in logs and storage. Jinko keeps each delivery payload for the delivery log and deletes it 30 days after the delivery’s last attempt or replay.

Completed bookings

booking.completed lists every booked item in data.items, so you can tell the traveler the airline or hotel reference without calling get_booking.

{
  "event": "booking.completed",
  "booking_ref": "JNK-8F3D21",
  "status": "confirmed",
  "occurred_at": "2027-06-02T08:00:00Z",
  "event_id": "evt_e5a09b3c7d12",
  "livemode": true,
  "data": {
    "items": [
      {
        "item_id": "prod_f5pyznimu4",
        "kind": "flight",
        "booked_item_id": "itm_4zq2c7mbx3k1a9pd",
        "supplier_references": [{ "issuer": "AF", "reference": "XM9L2K" }]
      }
    ],
    "manage_booking_url": "https://app.gojinko.com/bookings/JNK-8F3D21?ln=Martin",
    "customer_emails": [ … ]
  }
}

Field	Notes
`data.items[].item_id`	Matches `items[].item_id` on `get_trip`.
`data.items[].kind`	`flight`, `hotel` or `car`.
`data.items[].booked_item_id`	The item’s handle: `booked_item_id` on `get_booking`, and what a refund, exchange or cancellation takes.
`data.items[].supplier_references`	The supplier’s own confirmations, each `{ issuer, reference }`: the airline’s record locator per airline, the hotel’s confirmation number, or the rental reservation number. `[]` when none is known.

data.items is absent on events sent before contract 0.75.0.

Partial bookings

booking.partial carries data describing what actually happened per item and how much was captured.

{
  "event": "booking.partial",
  "booking_ref": "JNK-A7B3X9",
  "status": "partial",
  "occurred_at": "2027-09-02T08:00:00Z",
  "event_id": "evt_3b7e90d15fa2",
  "livemode": true,
  "data": {
    "items": [
      {
        "item_id": "prod_f5pyznimu4",
        "kind": "flight",
        "status": "completed",
        "supplier_references": [{ "issuer": "AF", "reference": "XM9L2K" }],
        "captured_amount_money": { "value": 18865, "currency": "USD", "decimal_places": 2, "display": "USD 188.65" },
        "captured_amount": { "amount": 188.65, "currency": "USD" }
      },
      {
        "item_id": "prod_h2k9qmz013",
        "kind": "hotel",
        "status": "failed"
      }
    ],
    "captured_total_money": { "value": 18865, "currency": "USD", "decimal_places": 2, "display": "USD 188.65" },
    "captured_total": { "amount": 188.65, "currency": "USD" }
  }
}

Field	Notes
`data.items[].item_id`	Matches `items[].item_id` on `get_trip`.
`data.items[].kind`	`flight`, `hotel` or `car`.
`data.items[].status`	`completed` or `failed`, per item.
`data.items[].supplier_references`	The supplier confirmations on an item that booked, each `{ issuer, reference }`: the airline’s record locator per airline, the hotel’s confirmation number, or the rental reservation number. `[]` when none is known. Absent on a failed item.
`data.items[].captured_amount_money`	What was charged for this item. Present only on items that booked.
`data.captured_total_money`	What the customer was actually charged: the items that booked, not the trip total, so it will not match the original quote.
`data.items[].captured_amount`, `data.captured_total`	Deprecated. The same figures in major units (`188.65`). Read the `*_money` fields instead.

The *_money fields use the platform’s one money shape: value is an integer in minor units, divide it by 10 ** decimal_places, and display is the same figure ready to show. See Money & prices. The deprecated captured_amount and captured_total are still sent, in major units, so do not divide those.

Failed bookings

booking.failed carries failure_reason when the failure has a classified cause: price_changed, offer_unavailable, booking_not_created or booking_cancelled_at_provider. failure_message, a customer-facing sentence, is sent for the first two causes only. Both are absent when the failure has no classified cause. customer_emails carries the booking-failed email.

Cancellations

servicing.completed reports a post-booking operation on one booked item, today a cancellation, that succeeded and whose money was settled. It is a separate event from booking.completed because it reports a booking being undone. Its data names the operation and the money, and carries the cancellation email in customer_emails (left out of this example):

{
  "event": "servicing.completed",
  "booking_ref": "JNK-A7B3X9",
  "status": "servicing.completed",
  "occurred_at": "2027-09-20T14:12:09Z",
  "event_id": "evt_c41a6e2b98d0",
  "livemode": true,
  "data": {
    "operation": "svc_8cd41f",
    "operation_kind": "cancel",
    "booked_item_id": "itm_aaaaaaaaaaaaafhuxsdxpbzrbfz5hm3a",
    "state": "succeeded",
    "refund": { "value": 25000, "currency": "USD", "decimal_places": 2, "display": "USD 250.00" },
    "penalty": { "value": 4500, "currency": "USD", "decimal_places": 2, "display": "USD 45.00" },
    "booking_ref": "JNK-A7B3X9",
    "servicing_event": "servicing.completed"
  }
}

Field	Notes
`data.operation`	The `svc_…` operation handle, the same one the commit returned and the status endpoints take.
`data.operation_kind`	What the operation did, e.g. `cancel`.
`data.booked_item_id`	The booked item the operation acted on: `booked_item_id` on `get_booking`.
`data.state`	Always `succeeded`. The event is sent only for an operation that succeeded.
`data.refund`	What was settled back to the customer for this item. `null` when the operation has no refund figure.
`data.penalty`	The supplier fee the customer agreed to. `null` when the operation has no fee figure.
`data.booking_ref`, `data.servicing_event`	The event-level `booking_ref` and the event name again.
`data.customer_emails`	The cancellation email for this item: `flight-cancellation`, `hotel-cancellation` or `car-cancellation`. See Customer emails.

refund and penalty use the same money shape as the *_money fields above, with decimal_places at the ISO 4217 digits of the currency. null means the operation carries no such figure, which is different from a figure of zero.

Exchanges and failed operations

servicing.exchange_confirmed, servicing.ticket_issued and servicing.failed each report one operation on one booked item. Their data carries:

Field	Notes
`data.operation_kind`	The operation: `cancel`, `void`, `exchange` or `refund`.
`data.booked_item_id`	The booked item the operation acted on, when known.
`data.booking_ref`	The booking’s Jinko reference, when known.
`data.operation`	The `svc_…` operation handle, when the operation has one.
`data.customer_emails`	The email Jinko sends at that moment: `flight-exchange`, `flight-exchange-ticket-number`, or `exchange-failed` or `refund-failed`.

The event_id is an opaque string, unique to each occurrence of an event. Its format is not part of the contract: don’t parse it. The four servicing.* events can happen more than once for the same booking, for example servicing.completed for each cancelled item, and each occurrence has its own event_id. Retries and replays reuse it, so your dedupe on X-Jinko-Event-Id covers them.

Each request also carries these headers:

Header	Purpose
`X-Jinko-Signature`	`sha256=<hex>` HMAC of the request (see below).
`X-Jinko-Timestamp`	Unix seconds; part of the signed payload (replay protection).
`X-Jinko-Event-Id`	Stable id for the business event; use it to dedupe.
`X-Jinko-Delivery-Id`	Id of this specific delivery attempt.

Verify the signature

Compute HMAC-SHA256(secret, "<X-Jinko-Timestamp>.<raw request body>") and compare it, in constant time, to the hex in X-Jinko-Signature (after the sha256= prefix). Use the raw request body: parsing and re-serializing the JSON will change the bytes and break the check.

Node.js
Python

import crypto from 'node:crypto';

// rawBody: the exact bytes Jinko sent (Buffer/string), NOT re-serialized JSON.
function verifyJinkoWebhook(rawBody, headers, secret) {
  const ts = headers['x-jinko-timestamp'];
  const sig = headers['x-jinko-signature'];
  const toleranceSeconds = 300;
  if (typeof ts !== 'string' || !/^[0-9]{1,12}$/.test(ts) ||
      typeof sig !== 'string' || !/^sha256=[a-fA-F0-9]{64}$/.test(sig)) {
    return false;
  }
  if (Math.abs(Date.now() / 1000 - Number(ts)) > toleranceSeconds) {
    return false;
  }
  const expected = crypto.createHmac('sha256', secret)
    .update(`${ts}.`).update(rawBody).digest();
  const received = Buffer.from(sig.slice('sha256='.length), 'hex');
  return received.length === expected.length &&
    crypto.timingSafeEqual(expected, received);
}

import hashlib
import hmac
import re
import time

def verify_jinko_webhook(raw_body: bytes, headers: dict, secret: str) -> bool:
    headers = {key.lower(): value for key, value in headers.items()}
    ts = headers.get("x-jinko-timestamp")
    sig = headers.get("x-jinko-signature")
    tolerance_seconds = 300
    if not isinstance(ts, str) or not re.fullmatch(r"[0-9]{1,12}", ts):
        return False
    if not isinstance(sig, str) or not re.fullmatch(r"sha256=[a-fA-F0-9]{64}", sig):
        return False
    if abs(time.time() - int(ts)) > tolerance_seconds:
        return False
    signed = f"{ts}.".encode() + raw_body
    expected = hmac.new(secret.encode(), signed, hashlib.sha256).digest()
    received = bytes.fromhex(sig[len("sha256="):])
    return len(received) == len(expected) and hmac.compare_digest(expected, received)

Reject the request if the signature doesn’t match, or if X-Jinko-Timestamp is outside your tolerance in either direction (the examples use 5 minutes) to guard against replays. Respond 2xx once you’ve accepted the event.

Handle retries and duplicates

Return 2xx as soon as you have stored the event. Process slower work asynchronously.
Jinko retries a timeout or non-2xx response with exponential backoff, up to 8 attempts over about 80 minutes.
Deduplicate retries with X-Jinko-Event-Id. Every attempt for the same business event uses the same value.
After the eighth failed attempt, the delivery becomes exhausted. You can replay it from the delivery log.

Inspect and replay deliveries

Jinko records every attempt to deliver an event.

Dashboard: open Webhooks in the dashboard, select the webhook, then open Deliveries. You can inspect each attempt and replay a delivery.
API with a legacy person-bound key: GET /v1/webhooks/{id}/deliveries lists deliveries. POST /v1/webhooks/{id}/deliveries/{delivery_id}/replay replays one.

`status`	Meaning
`pending`	Not attempted yet, or a replay is queued.
`delivered`	Your endpoint answered `2xx`.
`failed`	The last attempt failed and another one is scheduled. Deliveries that failed before this log existed are not retried and can’t be replayed.
`exhausted`	The last of the 8 attempts failed. Jinko does not retry it.

A replay sends the same event again: same event_id, same payload, signed with a new X-Jinko-Timestamp. It starts a fresh set of attempts and adds one to the delivery’s replay_count. Replay is accepted for a delivered or exhausted delivery. It is refused with 409 and code delivery_in_progress while the delivery is pending or failed, and with 409 and code payload_purged once the payload is deleted, 30 days after the delivery’s last attempt or replay. Because a replay keeps the event_id, a receiver that deduplicates on X-Jinko-Event-Id treats it as an event it already has, if it processed the first delivery.

Test the endpoint

The dashboard has no test button. With a legacy person-bound key, send a test event through the API:

curl -X POST https://api.gojinko.com/v1/webhooks/42/test \
  -H "X-API-Key: $JINKO_API_KEY"

This delivers a sample event with "livemode": false and booking_ref: "JNK-TEST00", so you can confirm your signature handling end-to-end without a real booking.

Getting started

Guides

Marketing claim

Authentication

Connect

Developer Platform

Concepts

How it works

Prerequisites

Tenant subscriptions

Register an endpoint

Choose events

Read the payload

Customer emails

Completed bookings

Partial bookings

Failed bookings

Cancellations

Exchanges and failed operations

Verify the signature

Handle retries and duplicates

Inspect and replay deliveries

Test the endpoint

​How it works

​Prerequisites

​Tenant subscriptions

​Register an endpoint

​Choose events

​Read the payload

​Customer emails

​Completed bookings

​Partial bookings

​Failed bookings

​Cancellations

​Exchanges and failed operations

​Verify the signature

​Handle retries and duplicates

​Inspect and replay deliveries

​Test the endpoint

How it works

Prerequisites

Tenant subscriptions

Register an endpoint

Choose events

Read the payload

Customer emails

Completed bookings

Partial bookings

Failed bookings

Cancellations

Exchanges and failed operations

Verify the signature

Handle retries and duplicates

Inspect and replay deliveries

Test the endpoint