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:
| Path | Configure with | Body | Authentication | Retries |
|---|---|---|---|---|
| Portal webhooks: portal accounts, in production and in the sandbox (Z0 test check-ins), up to 10 per environment | Settings > Webhooks; also POST /api/sandbox/v1/settings, or webhook_url on a Z0 check-in | Chosen per webhook: {status, checkin} or {event, timestamp, customer_id, data} | X-1Checkin-Signature when the webhook has a secret, plus your custom headers | 8 attempts over about 42 minutes, with a delivery history and manual retry |
| Direct Corp API: your own Corp account, not managed in the portal | POST /settings on the Corp API | {status, checkin} | Your push_api_headers | Up to 7 retries over about 42 minutes |
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:
{
"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"
}
}| event | Sent when |
|---|---|
checkin.completed | The check-in succeeded. |
checkin.failed | The check-in failed or was aborted. data.status is failed or cancelled. |
boarding_pass.ready | A 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_requested | Sandbox 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.
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:
| Header | Value |
|---|---|
User-Agent | 1Checkin-Webhooks/1.0 |
X-1Checkin-Event-Id | The event's id, the same on every attempt |
X-1Checkin-Delivery-Id | The id of this event's delivery to your endpoint |
X-1Checkin-Event-Type | The event, for example checkin.completed, or test for a test send |
X-1Checkin-Environment | production or sandbox |
X-1Checkin-Attempt | 1 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).
{
"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.
{
"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:
{
"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:
| Header | Value |
|---|---|
Content-Type | application/json |
X-1Checkin-Signature | Portal 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:
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');
});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', 200Configuring 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.
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
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
curl -X GET "https://app.1check.in/corp_api/v1/settings" \
-H "X-API-KEY: YOUR_CORP_API_KEY"Replace Webhook Settings
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.
| Attempt | Delay before | Cumulative time |
|---|---|---|
| Initial | (immediate) | 0s |
| Retry 1 | 20s | ~20s |
| Retry 2 | 40s | ~1 min |
| Retry 3 | 80s | ~2 min |
| Retry 4 | 160s | ~5 min |
| Retry 5 | 320s | ~10 min |
| Retry 6 | 640s | ~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.
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).
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.