Webhooks

Webhooks allow you to receive real-time notifications when check-in status changes. Instead of polling the API, add a webhook and we'll send updates automatically.

Delivery Paths

How you configure webhooks, and what you receive, depends on how your account reaches 1Checkin:

PathConfigure withBodyAuthenticationRetries
Portal webhooks: portal accounts, in production and in the sandbox (Z0 test check-ins), up to 10 per environmentSettings > Webhooks; also POST /api/sandbox/v1/settings, or webhook_url on a Z0 check-inChosen per webhook: {status, checkin} or {event, timestamp, customer_id, data}X-1Checkin-Signature when the webhook has a secret, plus your custom headers8 attempts over about 42 minutes, with a delivery history and manual retry
Direct Corp API: your own Corp account, not managed in the portalPOST /settings on the Corp API{status, checkin}Your push_api_headersUp to 7 retries over about 42 minutes
Portal-managed accounts: never call POST /settings on the Corp API

The portal registers its own callback receiver in your Corp settings. POST /settings replaces it, so callbacks stop reaching the portal and your webhooks. Add your webhooks in Settings > Webhooks instead.

Portal Format Payload

A webhook in the Portal format receives one request per event, with a JSON body of the form:

Portal format payload (checkin.completed)
json
{
  "event": "checkin.completed",
  "timestamp": "2026-01-19T10:30:15.123456+00:00",
  "customer_id": "YOUR_PORTAL_CUSTOMER_ID",
  "data": {
    "checkin_id": "504061687271",
    "status": "success",
    "pnr": "ABC123",
    "airline_code": "BA",
    "route": "LHR \u2192 JFK",
    "passengers": [{"name": "John Smith", "seat": "14A"}],
    "seat_assignments": ["14A"],
    "boarding_pass_urls": ["https://.../boarding-pass.pdf?signature=..."],
    "fail_reason": 100,
    "completed_at": "2026-01-19T10:30:14"
  }
}
eventSent when
checkin.completedThe check-in succeeded.
checkin.failedThe check-in failed or was aborted. data.status is failed or cancelled.
boarding_pass.readyA successful check-in includes a boarding pass. Sent in addition to checkin.completed, only if you select it. Only the Portal format carries this event.
checkin.info_requestedSandbox only: the check-in needs more passenger data. data.request lists the missing fields (see More info required).

Choose each webhook's events in Settings > Webhooks. Other intermediate statuses do not produce an event. A delivery that fails is retried (see Retry Policy), and the webhook's delivery history shows every attempt.

Verifying signed deliveries

When a webhook has a signing secret, each of its deliveries carries X-1Checkin-Signature: sha256=<hex>, the HMAC-SHA256 of the raw request body, in either payload format. Verify it over the exact bytes you received, before parsing, with a constant-time comparison.

Verify a signed delivery (Python)
python
import hashlib, hmac

def is_valid(raw_body: bytes, signature_header: str, secret: str) -> bool:
    expected = class="token-string">"sha256=" + hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(signature_header or class="token-string">"", expected)

Delivery headers

Every delivery to a portal webhook also carries these headers:

HeaderValue
User-Agent1Checkin-Webhooks/1.0
X-1Checkin-Event-IdThe event's id, the same on every attempt
X-1Checkin-Delivery-IdThe id of this event's delivery to your endpoint
X-1Checkin-Event-TypeThe event, for example checkin.completed, or test for a test send
X-1Checkin-Environmentproduction or sandbox
X-1Checkin-Attempt1 for the first attempt, 2 for the first retry, and so on

Delivery is at least once: a retry after a timeout can repeat an event you already processed, so deduplicate on X-1Checkin-Event-Id. Events can arrive out of order.

When Corp API Format Webhooks Fire

A webhook in the Corp API format, like a direct Corp API account, fires once per check-in when it reaches a terminal status: success, failed, or aborted. The boarding pass URL is part of the success payload (in checkin.files[]); this format has no separate boarding-pass notification.

One additional, non-terminal event exists: requested_extra_info ("more info required"), sent when the automation needs more data from you before it can proceed. It is opt-in; see More info required below.

Corp API Format Payload

Each webhook is a POST request with a JSON body. The payload has two top-level fields: status (the terminal status) and checkin (the full check-in object, the same shape GET /checkin/{id} returns).

Webhook payload (successful check-in)
json
{
  "status": "success",
  "checkin": {
    "id": 504061687271,
    "booking_id": 980972996354,
    "remote_id": "BOOKING-12345",
    "data": {
      "passengers": [{
        "num": 1,
        "remote_id": "pax_1",
        "first_name": "John",
        "last_name": "Smith",
        "boarding_seat": "14A",
        "boarding_info": {
          "pnr": "ABC123",
          "seat": "14A",
          "flight": "BA 178",
          "origin": "LHR",
          "destination": "JFK",
          "first_name": "John",
          "last_name": "Smith"
        }
      }],
      "flights": [/* ... */]
    },
    "files": [{
      "url": "https://files.example.com/boarding-pass.pdf?SIGNED_QUERY",
      "filetype": "boardingPass",
      "file_type": "boardingPass",
      "content_type": "application/pdf",
      "expires": 1809849600
    }],
    "status": "success",
    "fail_reason": 100,
    "scheduled_checkin_time": "2026-01-19T10:30:00+00:00",
    "finished_time": "2026-01-19T10:30:14+00:00"
  }
}

Download the exact checkin.files[].url, including its query string, without your API key. Its host can differ from the API host. files.example.com is illustrative, not a production hostname or an allowlist; sandbox file URLs are sandbox-only.

Webhook payload (failed check-in)
json
{
  "status": "failed",
  "checkin": {
    "id": 504061687271,
    "booking_id": 980972996354,
    "remote_id": "BOOKING-12345",
    "data": { "passengers": [/* ... */], "flights": [/* ... */] },
    "files": [],
    "status": "failed",
    "fail_reason": 200,
    "finished_time": "2026-01-19T10:30:14+00:00"
  }
}

More Info Required (requested_extra_info)

Sometimes the automation needs additional passenger data (a missing e-ticket number, document details) before it can complete the check-in. When that happens the check-in moves to status requested_extra_info and, if enabled, a webhook fires with the same {status, checkin} shape. The checkin.request array names the missing fields as JSON paths into the check-in object:

Webhook payload (more info required)
json
{
  "status": "requested_extra_info",
  "checkin": {
    "id": 504061687271,
    "booking_id": 980972996354,
    "remote_id": "BOOKING-12345",
    "data": { "passengers": [/* ... */], "flights": [/* ... */] },
    "files": [],
    "status": "requested_extra_info",
    "fail_reason": null,
    "request": ["passengers.0.eticket"],
    "finished_time": null
  }
}

Respond by sending the missing fields via PUT /v1/checkin/{id} (see Update Check-in). The check-in returns to idle and continues to a terminal status, which produces the normal terminal webhook. If you never respond, the check-in eventually fails with fail_reason: 201 (no response to the data request); in the sandbox this timeout is fixed at 30 minutes, in production it is configurable per account.

This event is opt-in. A sandbox webhook in Settings > Webhooks receives it when subscribed to More information requested (checkin.info_requested). The Sandbox API settings webhook and a direct Corp API account receive it with push_api_request_enabled: true on the settings call (alongside push_api_enabled). Sandbox check-ins created with a per-request webhook_url receive these events without any flag. Production webhooks in the portal do not receive this event. Test the full flow with Z0 flight number 201 (see Testing with the Z0 test airline).

Webhook Headers

Every delivery sends:

HeaderValue
Content-Typeapplication/json
X-1Checkin-SignaturePortal webhooks with a signing secret: sha256= plus the hex HMAC-SHA256 of the raw body. Direct Corp API deliveries are not signed.

Custom headers are sent with every request: the ones you add to a webhook in Settings > Webhooks, or push_api_headers for the Sandbox API settings and a direct Corp API account. Use them for shared-secret authentication on your receiver. The headers 1Checkin sets itself, such as Content-Type, User-Agent and the X-1Checkin- headers, cannot be replaced.

Verifying Unsigned Webhooks

Direct Corp API deliveries are not signed, and neither is the Sandbox API settings webhook until you rotate its secret in Settings. Configure a custom header (e.g. Authorization) and check the value on your receiver. Example handler:

Webhook handler (Node.js)
javascript
const SHARED_SECRET = process.env.WEBHOOK_SHARED_SECRET;

app.post(class="token-string">'/webhooks/checkin', (req, res) => {
  const auth = req.headers[class="token-string">'authorization'];
  if (auth !== class="token-string">`Bearer ${SHARED_SECRET}`) {
    return res.status(401).send(class="token-string">'Invalid auth');
  }

  class=class="token-string">"token-comment">// Process the webhook
  const { status, checkin } = req.body;
  console.log(class="token-string">`Received ${status} for check-in ${checkin.id}`);

  if (status === class="token-string">'success') {
    class=class="token-string">"token-comment">// Select BY TYPE, never by position: files[0] can be a screenshot or a
    class=class="token-string">"token-comment">// check-in confirmation, so taking the first entry silently hands you
    class=class="token-string">"token-comment">// the wrong document. Inspect BOTH type fields independently, since a
    class=class="token-string">"token-comment">// record may carry the value on only one of them.
    const isBoardingPass = (f) => [f.filetype, f.file_type]
      .some((t) => t === class="token-string">'boardingPass' || t === class="token-string">'boarding_pass');
    const bpUrl = (checkin.files || []).find(isBoardingPass)?.url;
    if (bpUrl) {
      class=class="token-string">"token-comment">// Download the boarding pass from the presigned URL.
    }
  }

  res.status(200).send(class="token-string">'OK');
});
Webhook handler (Python / Flask)
python
import os
SHARED_SECRET = os.environ[class="token-string">'WEBHOOK_SHARED_SECRET']

@app.route(class="token-string">'/webhooks/checkin', methods=[class="token-string">'POST'])
def handle_webhook():
    auth = request.headers.get(class="token-string">'Authorization')
    if auth != fclass="token-string">"Bearer {SHARED_SECRET}":
        return class="token-string">'Invalid auth', 401

    payload = request.json
    status = payload[class="token-string">'status']            class=class="token-string">"token-comment"># class="token-string">"success" or class="token-string">"failed"
    checkin = payload[class="token-string">'checkin']          class=class="token-string">"token-comment"># full GET /checkin/{id} shape
    print(fclass="token-string">"Received {status} for check-in {checkin['id']}")

    if status == class="token-string">'success' and checkin.get(class="token-string">'files'):
        for f in checkin[class="token-string">'files']:
            if f.get(class="token-string">'filetype') in (class="token-string">'boardingPass', class="token-string">'boarding_pass'):
                class=class="token-string">"token-comment"># Download the boarding pass from f[class="token-string">'url'].
                pass

    return class="token-string">'OK', 200

Configuring Webhooks

Portal accounts

Add and manage up to 10 webhooks per environment in Settings > Webhooks; Webhook Configuration describes every option. Only account admins and developers can change webhooks.

Sandbox API settings

POST /api/sandbox/v1/settings updates only the fields you send, and changes the webhook shown in Settings as Sandbox API settings. GET /api/sandbox/v1/settings returns its current values.

Set the sandbox webhook
curl
curl -X POST "https://1checkin.com/api/sandbox/v1/settings" \
  -H "X-API-KEY: YOUR_SANDBOX_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "push_api_enabled": true,
    "push_api_request_enabled": true,
    "push_api_status_url": "https://your-server.com/webhooks/checkin",
    "push_api_headers": {
      "Authorization": "Bearer your-shared-secret"
    }
  }'

Legacy direct Corp API accounts

POST /settings replaces every push setting

Send all push fields on every call. An omitted push_api_enabled turns webhooks off, an omitted push_api_headers removes your authentication header, and an omitted push_api_request_enabled turns off more-info events.

Get Current Settings

Get webhook settings with a legacy Corp-issued key
curl
curl -X GET "https://app.1check.in/corp_api/v1/settings" \
  -H "X-API-KEY: YOUR_CORP_API_KEY"

Replace Webhook Settings

Set webhook URL, headers and events with a legacy Corp-issued key
curl
curl -X POST "https://app.1check.in/corp_api/v1/settings" \
  -H "X-API-KEY: YOUR_CORP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "push_api_enabled": true,
    "push_api_request_enabled": true,
    "push_api_status_url": "https://your-site.com/webhooks/checkin",
    "push_api_headers": {
      "Authorization": "Bearer your-shared-secret"
    }
  }'

push_api_request_enabled additionally opts the account-level URL into the non-terminal requested_extra_info event; set it to false to receive terminal statuses only.

Retry Policy

Deliveries are retried with exponential backoff: the delay before each retry doubles, for up to 8 attempts over about 42 minutes.

AttemptDelay beforeCumulative time
Initial(immediate)0s
Retry 120s~20s
Retry 240s~1 min
Retry 380s~2 min
Retry 4160s~5 min
Retry 5320s~10 min
Retry 6640s~21 min
Retry 7 (final)1280s~42 min

Portal webhooks vary each delay by up to 10%, and an attempt may take up to 30 seconds. They retry timeouts, connection and DNS errors, redirects (which are not followed) and HTTP 401, 403, 404, 408, 425, 429 and 5xx responses. Any other 4xx response, or a destination the address policy blocks, ends the delivery. On 429 and 503 they wait as long as your Retry-After header asks, up to one hour. After the last attempt the delivery is marked failed. Finished deliveries stay in the webhook's delivery history for 30 days, and an account admin or developer can retry a failed delivery up to 3 times while its payload is kept, which is 30 days from when it was created.

Direct Corp API deliveries give each attempt 3 seconds and give up after 7 retries. There is no dead-letter queue; to recover a missed delivery, fetch GET /checkin/{id} directly to read the current state.

Respond Quickly

Acknowledge the webhook immediately (200 OK) and process asynchronously if you need to do anything heavier than parsing the payload.

Testing Webhooks

For a portal webhook, use Send test in Settings > Webhooks: it sends one test request in the webhook's format, signed with its secret, with X-1Checkin-Event-Type: test. For the sandbox, the simplest end-to-end test is a Z0 sandbox check-in for today's date: the synthetic worker flips status to success within seconds and your endpoint receives a real webhook payload (with files[] populated).

Trigger a webhook via a Z0 sandbox check-in
curl
curl -X POST "https://1checkin.com/api/sandbox/v1/checkins" \
  -H "X-API-KEY: YOUR_SANDBOX_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "remote_id": "WEBHOOK-TEST-1",
    "passengers": [{"first_name":"Test","last_name":"User","remote_id":"pax_1"}],
    "flights": [{
      "marketing_carrier_code":"Z0","operating_carrier_code":"Z0",
      "flight_num":"100","booking_ref":"TST",
      "departure_date":"'"$(date -u +%Y-%m-%d)"'","departure_time":"23:59",
      "departure_code":"LHR","destination_code":"JFK"
    }]
  }'

Three terminal payloads exist: {"status": "success", ...}, {"status": "failed", ...}, and {"status": "aborted", ...}, plus the opt-in requested_extra_info informational event. The boarding pass URL is part of the success payload via checkin.files[]. To exercise the more-info flow end-to-end, repeat the call above with flight_num: "201": your endpoint first receives the requested_extra_info event, and after you PUT the requested eticket it receives the success terminal event. See the Webhook setup guide for a complete handler example.

Related