Webhooks

Webhooks push booking lifecycle events to your server so you don’t have to poll. Register an HTTPS endpoint and Jinko sends a signed POST the moment a booking is confirmed or fails. The one-line version:

register endpoint → Jinko POSTs a signed event → you verify X-Jinko-Signature → you act

Prerequisites

A Jinko account and a user-bound API key (jnk_...). Get one.
An HTTPS endpoint that can receive a POST (must be https:// and publicly reachable).

/v1/webhooks does not accept tenant keys. A tenant-scoped key (jnk_t_…) is rejected on every route under /v1/webhooks. This is deliberate, not a gap: subscription management is an account-owner action, so it is bound to a person, not to a machine credential.If you hold a tenant key, register your endpoint in the dashboard instead, at Dashboard → Webhooks, picking your tenant from the selector. Bookings made with that tenant key then deliver to that subscription. There is no plan to add a webhooks scope to tenant keys, so don’t build around one arriving.

Tenant-key bookings deliver to the tenant’s own subscription

A booking made with a tenant key is owned by the tenant, not by a person, and its events go to the subscriptions registered against that tenant in the dashboard. Nothing about the payload, the headers, or the signature differs from a user-key delivery: the only difference is which subscription list the platform resolves. Register the endpoint once, in the dashboard, with your tenant picked in the selector. Then book with the tenant key. Every subscription that tenant owns and that names the event receives the same signed POST a user-key booking would produce.

Availability, as of 7 September 2026. Tenant-key delivery arrives with published contract 0.5.0. On sandbox it works once that release is deployed there; check info.version on the OpenAPI document for the environment you are calling. On production it additionally waits on a separate platform release, so a production booking made with a tenant key does not reach a tenant subscription yet.Bookings made with a user-bound key are unaffected in both environments and deliver normally.Nothing on your side needs to change when it lands: register the subscription in the dashboard now and it starts receiving. This note is removed once both releases have shipped.

1) Register an endpoint

Dashboard
API

Go to Dashboard → Webhooks, click Add webhook, paste your URL, pick the events, and Create. Copy the signing secret shown once. You’ll 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": "2026-06-02T08:00:00Z"
}

2) Events

Event	`status`	When it fires
`booking.completed`	`confirmed`	Every item in the trip was booked and paid (payment captured).
`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.

Exactly one of the three fires per trip. They are mutually exclusive.

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. booking.partial arrived in published contract 0.2.0. Check info.version in the OpenAPI document to confirm which contract an environment is serving.

3) Payload

Deliveries are intentionally thin: identifiers only, no traveler PII. Fetch full detail with get_booking using the booking_ref.

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

Those six fields are on every event and never change.

`booking.partial` adds a `data` object

booking.partial carries one extra top-level field, data, describing what actually happened per item and how much was captured. booking.completed and booking.failed do not carry data, so nothing changes for consumers you already have in production.

{
  "event": "booking.partial",
  "booking_ref": "JNK-A7B3X9",
  "status": "partial",
  "occurred_at": "2026-09-02T08:00:00Z",
  "event_id": "evt_402_booking.partial",
  "livemode": true,
  "data": {
    "items": [
      {
        "item_id": "prod_f5pyznimu4",
        "kind": "flight",
        "status": "completed",
        "booking_reference": "JNK-A7B3X9",
        "captured_amount": { "amount": 188.65, "currency": "USD" }
      },
      {
        "item_id": "prod_h2k9qmz013",
        "kind": "hotel",
        "status": "failed"
      }
    ],
    "captured_total": { "amount": 188.65, "currency": "USD" }
  }
}

Field	Notes
`data.items[].item_id`	Matches `items[].item_id` on `get_trip`.
`data.items[].kind`	`flight` or `hotel`.
`data.items[].status`	`completed` or `failed`, per item.
`data.items[].booking_reference`	Present only on items that booked.
`data.items[].captured_amount`	Present only on items that booked. Major units, e.g. `188.65`.
`data.captured_total`	What the customer was actually charged. Major units.

Amounts here are in major units (188.65), matching the Money shape used across the trip and checkout responses. This differs from the minor-unit form used elsewhere in the platform, so don’t divide by 100.

The event_id for a partial is evt_<fulfillment_cart_id>_booking.partial, one per trip. Retries reuse it, so your existing dedupe on X-Jinko-Event-Id covers it with no change.

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.

4) 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']; // "sha256=<hex>"
  const expected =
    'sha256=' +
    crypto.createHmac('sha256', secret).update(`${ts}.${rawBody}`).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(sig));
}

import hashlib
import hmac

def verify_jinko_webhook(raw_body: bytes, headers: dict, secret: str) -> bool:
    ts = headers["X-Jinko-Timestamp"]
    sig = headers["X-Jinko-Signature"]  # "sha256=<hex>"
    signed = f"{ts}.".encode() + raw_body
    expected = "sha256=" + hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, sig)

Reject the request if the signature doesn’t match, or if X-Jinko-Timestamp is older than your tolerance (e.g. 5 minutes) to guard against replays. Respond 2xx once you’ve accepted the event.

5) Retries & idempotency

A non-2xx response (or a timeout) is retried with exponential backoff, up to 8 attempts over several hours.
Retries mean you may receive the same event more than once. Deduplicate on X-Jinko-Event-Id (a given business event always carries the same id).
Return 2xx as soon as you’ve durably recorded the event; do slow work asynchronously so you don’t trip the delivery timeout.

6) Test it

Use Send test in the dashboard, or:

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

Authentication

Connect

Concepts

Prerequisites

Tenant-key bookings deliver to the tenant’s own subscription

1) Register an endpoint

2) Events

3) Payload

`booking.partial` adds a `data` object

4) Verify the signature

5) Retries & idempotency

6) Test it

​Prerequisites

​Tenant-key bookings deliver to the tenant’s own subscription

​1) Register an endpoint

​2) Events

​3) Payload

​booking.partial adds a data object

​4) Verify the signature

​5) Retries & idempotency

​6) Test it

Prerequisites

Tenant-key bookings deliver to the tenant’s own subscription

1) Register an endpoint

2) Events

3) Payload

`booking.partial` adds a `data` object

4) Verify the signature

5) Retries & idempotency

6) Test it