Webhook Setup Guide

Webhooks let you receive real-time notifications when check-in status changes. This is the recommended approach instead of polling the API.

First, find your delivery path

Portal account (production or sandbox): add up to 10 webhooks per environment in Settings > Webhooks (see Webhook Configuration). For an account activated in the portal, do not call POST /settings on the Corp API: it replaces the portal's callback registration, and production events stop reaching the portal.

Sandbox API: POST /api/sandbox/v1/settings still sets one webhook, shown in Settings as Sandbox API settings, and a Z0 check-in can name its own webhook_url.

Direct Corp API integration (your own Corp account, not managed in the portal): set your one URL with POST /settings on the Corp API, sending every push field each time.

Real-time Updates

Get notified immediately when something happens

Authenticated

Signed with your webhook's secret, or your own shared-secret header

Self-describing

Every payload carries the check-in id and status

Step 1: Create a Webhook Endpoint

Create an endpoint on your server to receive webhook requests. The endpoint must accept POST requests and return a 2xx status code. The examples below handle the Corp API format, {status, checkin}: the default for new webhooks, and what the Sandbox API settings and a direct Corp API account send. A webhook in the Portal format receives {event, timestamp, customer_id, data} instead; see Step 3.

Express.js webhook endpoint
javascript
const express = require(class="token-string">'express');
const app = express();

class=class="token-string">"token-comment">// Parse JSON bodies
app.use(express.json());

class=class="token-string">"token-comment">// Webhook endpoint
app.post(class="token-string">'/webhooks/checkin', (req, res) => {
  const { status, checkin } = req.body;
  console.log(class="token-string">`Received ${status} for check-in ${checkin?.id}`);

  if (status === class="token-string">'success') {
    const passenger = checkin.data.passengers[0];
    console.log(class="token-string">`Check-in complete! Seat: ${passenger.boarding_seat}`);

    class=class="token-string">"token-comment">// Download boarding passes from checkin.files[]
    for (const f of checkin.files || []) {
      if (f.filetype === class="token-string">'boardingPass' || f.filetype === class="token-string">'boarding_pass') {
        class=class="token-string">"token-comment">// GET f.url with no auth header to fetch the PDF binary.
        downloadBoardingPass(checkin.id, f.url);
      }
    }
  } else if (status === class="token-string">'failed') {
    class=class="token-string">"token-comment">// checkin.fail_reason is a numeric result code, e.g. 200, 420 or 503.
    console.log(class="token-string">`Check-in failed: fail_reason=${checkin.fail_reason}`);
  }

  class=class="token-string">"token-comment">// Respond quickly: an attempt gets 30 seconds (3 on the direct Corp API)
  res.status(200).send(class="token-string">'OK');
});

app.listen(3000);
Flask webhook endpoint
python
from flask import Flask, request, jsonify

app = Flask(__name__)

@app.route(class="token-string">'/webhooks/checkin', methods=[class="token-string">'POST'])
def handle_webhook():
    payload = request.json
    status = payload.get(class="token-string">'status')        class=class="token-string">"token-comment"># class="token-string">"success" or class="token-string">"failed"
    checkin = payload.get(class="token-string">'checkin', {})  class=class="token-string">"token-comment"># full GET /checkin/{id} shape

    checkin_id = checkin.get(class="token-string">'id')
    print(fclass="token-string">"Received {status} for check-in {checkin_id}")

    if status == class="token-string">'success':
        for psg in checkin.get(class="token-string">'data', {}).get(class="token-string">'passengers', []):
            seat = psg.get(class="token-string">'boarding_seat') or class="token-string">'(no seat)'
            print(fclass="token-string">"{psg.get('first_name')} checked in, seat {seat}")
        for f in checkin.get(class="token-string">'files', []):
            if f.get(class="token-string">'filetype') in (class="token-string">'boardingPass', class="token-string">'boarding_pass'):
                print(fclass="token-string">"Boarding pass: {f['url']}")
                class=class="token-string">"token-comment"># Download from f[class="token-string">'url'] (presigned URL, no auth needed)

    elif status == class="token-string">'failed':
        fail_reason = checkin.get(class="token-string">'fail_reason')
        print(fclass="token-string">"Check-in failed: fail_reason={fail_reason}")
        class=class="token-string">"token-comment"># See /docs/guides/error-handling for fail_reason codes

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

if __name__ == class="token-string">'__main__':
    app.run(port=3000)

Step 2: Make Your Endpoint Publicly Accessible

Your webhook endpoint must be accessible from the internet. For local development, you can use a tunneling service:

Using ngrok for local development
bash
"token-comment"># Install ngrok (https://ngrok.com)
ngrok http 3000

"token-comment"># You'll get a URL like:
"token-comment"># https://abc123.ngrok.io

"token-comment"># Use this as your webhook URL:
"token-comment"># https://abc123.ngrok.io/webhooks/checkin
Production Requirements

Your endpoint must use HTTPS and be on a reliable server with good uptime. We won't deliver webhooks to HTTP endpoints, localhost, or private network addresses, and the URL must not contain a username or password.

Step 3: Authenticate Incoming Webhooks

Webhooks with a signing secret: verify the signature

Every webhook you add in Settings > Webhooks has a signing secret, and each of its deliveries carries X-1Checkin-Signature: sha256=<hex>, the HMAC-SHA256 of the raw request body. Compute it over the exact bytes you received, before any JSON parsing, and compare in constant time. The check is the same for both payload formats; the examples below read the Portal format.

Verify a signed delivery (Node.js)
javascript
const crypto = require(class="token-string">'crypto');
const SIGNING_SECRET = process.env.WEBHOOK_SIGNING_SECRET;

class=class="token-string">"token-comment">// express.raw keeps the exact bytes the signature covers.
app.post(class="token-string">'/webhooks/1checkin', express.raw({ type: class="token-string">'application/json' }), (req, res) => {
  const expected = class="token-string">'sha256=' + crypto
    .createHmac(class="token-string">'sha256', SIGNING_SECRET)
    .update(req.body)
    .digest(class="token-string">'hex');
  const received = req.get(class="token-string">'X-1Checkin-Signature') || class="token-string">'';
  if (received.length !== expected.length ||
      !crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected))) {
    return res.status(401).send(class="token-string">'Invalid signature');
  }

  const { event, data } = JSON.parse(req.body);
  console.log(class="token-string">`${event} for check-in ${data.checkin_id} (${data.status})`);
  res.status(200).send(class="token-string">'OK');
});
Verify a signed delivery (Python / Flask)
python
import hashlib, hmac, json, os
SIGNING_SECRET = os.environ[class="token-string">'WEBHOOK_SIGNING_SECRET'].encode()

@app.route(class="token-string">'/webhooks/1checkin', methods=[class="token-string">'POST'])
def signed_webhook():
    raw = request.get_data()  class=class="token-string">"token-comment"># exact bytes, before parsing
    expected = class="token-string">'sha256=' + hmac.new(SIGNING_SECRET, raw, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(request.headers.get(class="token-string">'X-1Checkin-Signature', class="token-string">''), expected):
        return class="token-string">'Invalid signature', 401

    payload = json.loads(raw)
    print(payload[class="token-string">'event'], payload[class="token-string">'data'][class="token-string">'checkin_id'], payload[class="token-string">'data'][class="token-string">'status'])
    return class="token-string">'OK', 200

Unsigned deliveries: a shared-secret header

Direct Corp API deliveries are never signed, and the Sandbox API settings webhook is signed only after you rotate its secret in Settings. Add a custom header (for example Authorization) to the webhook, and check its value on your receiver. The header is sent on every delivery.

Verify the shared secret (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 webhook...
  res.status(200).send(class="token-string">'OK');
});

Step 4: Configure Your Webhook URL

Portal accounts: Settings > Webhooks

Open Settings > Webhooks, choose Production or Sandbox, and select Add webhook. Enter your HTTPS URL, choose the events and the payload format, add any custom headers, and copy the signing secret when it is shown. Each environment holds up to 10 webhooks, and only account admins and developers can add or change them. See Webhook Configuration for every option.

Sandbox API settings

POST /api/sandbox/v1/settings updates only the fields you send. It changes the webhook shown in Settings as Sandbox API settings, which is stored in the portal and never forwarded to Corp:

Configure 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_status_url": "https://your-server.com/webhooks/checkin",
    "push_api_headers": {
      "Authorization": "Bearer your-shared-secret"
    }
  }'

Legacy direct Corp API integration

POST /settings replaces every push setting

Send all push fields on every call. An omitted push_api_enabled turns webhooks off, and an omitted push_api_headers removes your authentication header. Never use this on an account activated in the 1Checkin Portal.

Configure the webhook 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": false,
    "push_api_status_url": "https://your-server.com/webhooks/checkin",
    "push_api_headers": {
      "Authorization": "Bearer your-shared-secret"
    }
  }'
Where each event goes

A portal account sends each event to every webhook of its environment that is subscribed to it, up to 10 per environment. A direct Corp API account has one URL. Production check-ins have no per-request webhook URL, while a Z0 sandbox check-in created with its own webhook_url sends all of its events to that URL only, instead of to your sandbox webhooks.

Step 5: Test Your Webhook

For a webhook in Settings > Webhooks, select Send test: your endpoint receives one test request in the webhook's payload format, signed with its secret, with X-1Checkin-Event-Type: test. The result appears in the webhook's delivery history.

For the sandbox, create a Z0 sandbox check-in for today's date: the synthetic worker flips the status to success within seconds and your endpoint receives the webhook payload:

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

Wait ~30 seconds. Your endpoint should receive a POST with body {"status": "success", "checkin": {...}}. See the Webhooks reference for the full payload shape.

Handling the Statuses

Terminal webhooks carry success, failed, or aborted (a check-in you cancelled via abort). A sandbox webhook subscribed to More information requested (for the Sandbox API settings webhook, push_api_request_enabled) also receives the non-terminal requested_extra_info event when the automation needs more data. Respond with PUT /v1/checkin/{id} supplying the fields named in checkin.request (see the Webhooks reference).

The Portal format reports the same outcomes as events: checkin.completed for success, checkin.failed for failed or aborted (data.status is failed or cancelled), checkin.info_requested in the sandbox, and boarding_pass.ready when a boarding pass is attached.

status: success

The check-in succeeded. checkin.files[] contains presigned URLs for the boarding pass(es). Download each exact returned URL, including its query string, without your API key. The file host can differ from the API host; do not prepend the API base URL or construct production URLs from sandbox file paths. Store the files, then notify the customer.

javascript
if (status === class="token-string">'success') {
  await updateBookingStatus(checkin.remote_id, class="token-string">'checked_in');

  class=class="token-string">"token-comment">// Download and store boarding passes
  for (const f of checkin.files || []) {
    if (f.filetype === class="token-string">'boardingPass' || f.filetype === class="token-string">'boarding_pass') {
      const pdf = await fetch(f.url).then(r => r.arrayBuffer());
      await storeBoardingPass(checkin.id, pdf);
    }
  }

  await sendBoardingPassEmail(checkin.remote_id);
}

status: failed

The check-in failed. checkin.fail_reason is a numeric result code; see the Error handling guide for common codes and how to handle them. These are check-in result codes, not HTTP status codes. A failed result is terminal; do not assume an automatic retry or create a duplicate request.

javascript
if (status === class="token-string">'failed') {
  class=class="token-string">"token-comment">// Production returns numbers. Also tolerate legacy numeric strings.
  const failReason = /^\d+$/.test(String(checkin.fail_reason))
    ? Number(checkin.fail_reason) : null;

  if ([200, 220, 221, 222].includes(failReason)) {
    class=class="token-string">"token-comment">// Verify booking reference, ticket or passenger name as appropriate.
    await requestBookingVerification(checkin.remote_id);
  } else {
    class=class="token-string">"token-comment">// Includes 400 (window closed), 420 (airport-desk classification),
    class=class="token-string">"token-comment">// technical codes and unknown results. Confirm the next action with
    class=class="token-string">"token-comment">// support; the code alone does not establish the underlying cause.
    await alertSupport({ checkinId: checkin.id, failReason });
  }
}

Best Practices

Respond Quickly

Process webhooks asynchronously. Respond with 200 OK immediately, then handle the event in a background job.

Be Idempotent

The same event can arrive more than once. For portal webhooks, deduplicate on X-1Checkin-Event-Id, which stays the same on every attempt. For direct Corp API deliveries, deduplicate on checkin.id and status.

Log Everything

Log all webhook payloads and processing results for debugging. Include the check-in id in every log line so you can correlate later.

Know the Retry Behaviour

Portal webhooks, including the Sandbox API settings webhook and a check-in's own webhook_url, make up to 8 attempts over about 42 minutes, with 30 seconds for each; the Webhooks API reference lists the responses they retry. The delivery history shows every attempt, and a failed delivery can be retried by hand. Direct Corp API deliveries retry non-2xx responses and timeouts up to 7 times over the same period, with 3 seconds per attempt.

Troubleshooting

ProblemSolution
Not receiving webhooks (portal account)In Settings > Webhooks, check the environment, that the webhook is enabled and subscribed to the event, and open its delivery history for the last attempt and why it stopped; confirm your endpoint is publicly reachable over HTTPS.
Not receiving direct Corp API webhooksConfirm push_api_enabled: true via GET /settings; confirm endpoint is publicly reachable from the internet (not behind a VPN); confirm HTTPS cert is valid.
Signature does not matchCompute the HMAC over the raw request body, not over re-encoded JSON, with that webhook's secret. An admin or developer can reveal or rotate it in Settings > Webhooks.
Receiving 401 from your handlerCheck that your receiver expects the custom header set on the webhook in Settings > Webhooks, or in push_api_headers for the Sandbox API settings or a direct Corp API account. Saved header values are not shown, so replace them if in doubt.
Receiving duplicate deliveriesRetries can deliver the same event more than once. Deduplicate on X-1Checkin-Event-Id for portal webhooks, and on the check-in id and status for direct Corp API deliveries.
Webhooks arriving lateCheck your endpoint response time. An attempt that takes longer than 30 seconds (3 seconds on the direct Corp API) times out and is retried later.

Next Steps

Sending the boarding pass from your own domain

The check-in API does not send passenger mail from a partner domain. If your passengers should receive the boarding pass from your brand, your webhook worker does the delivery and 1Checkin is not in the mail path at all.

  1. Acknowledge fast. Return 2xx as soon as you have persisted the event. Do the download and the send afterwards, out of band; the retry schedule is not a queue for your side effects.
  2. Deduplicate on the check-in id. Webhooks retry, so the same successful check-in can arrive more than once. Without a dedupe key your passenger gets the same boarding pass twice.
  3. Download the signed URL server-side, and never log it. The URL is a bearer credential: anyone holding it can fetch the pass until it expires. Keep it out of logs, error trackers and analytics.
  4. Send through your own verified ESP and domain, with your own SPF, DKIM and DMARC alignment. This is what makes the message come from you.

If the passenger-visible link itself must be on your domain, the signed URL cannot be used directly: it points at our storage and it expires. Either copy the file into storage you control and serve your own link, or put an authenticated proxy on your domain that fetches it for a logged-in passenger. Do not embed the signed URL in a page you publish.

The passenger email field does not trigger delivery. It is passed to the airline as passenger data. Adding an address there does not cause 1Checkin, or the airline, to send your passenger their boarding pass.

Separately, 1Checkin has an optional built-in co-branded email. It sends from the fixed address trips@1checkin.com, not from your domain, so it is an alternative to the flow above rather than a way to achieve it.