Webhook Configuration

Portal accounts manage their webhooks in Settings > Webhooks: up to 10 webhooks for production and 10 for sandbox, each with its own events, payload format, signing secret and delivery history.

Open Settings > WebhooksAny member of your account can see the webhooks. Account admins and developers can add and change them.
Do not point Corp's callback URL at your server.

For an account activated in the 1Checkin Portal, calling POST /settings on the Corp API replaces the portal's callback registration, so production events stop reaching the portal and your webhooks. Add your URLs in Settings > Webhooks instead.

Production and sandbox

Switch between the two environments at the top of the tab. Production webhooks receive the events of your live check-ins, and become available once your account has gone live. Sandbox webhooks receive the events of Z0 test check-ins made with your sandbox key, so you can build and test your receiver first.

Adding a webhook

  1. Endpoint URL. An HTTPS URL on the public internet. Private and internal addresses are refused, and redirects are not followed.
  2. Events. The events this webhook receives; see the table below.
  3. Payload format. The Corp API format, the default for new webhooks, or the Portal format; see below.
  4. Custom headers (optional). Static headers sent with every delivery, such as a key your receiver checks. Their values are stored encrypted and never shown again.
  5. Signing secret. Every new webhook gets one. Copy it when it is shown; an admin or developer can reveal it again later, or rotate it.

Events

EventSent whenEnvironmentsFormats
checkin.completedThe check-in succeeded.Production and sandboxBoth
checkin.failedThe check-in failed or was aborted.Production and sandboxBoth
boarding_pass.readyA successful check-in includes a boarding pass. Sent in addition to checkin.completed.Production and sandboxPortal format
checkin.info_requestedThe check-in needs more passenger data before it can continue.SandboxBoth

Payload formats

FormatBodyContents
Corp API format{"status", "checkin"}The check-in as GET /checkin/{id} returns it, under its status. The default for new webhooks.
Portal format{"event", "timestamp", "customer_id", "data"}A short event summary: the check-in id, status, PNR, airline, route, passengers, seats, boarding pass links and failure reason.

Every delivery to a webhook with a signing secret carries X-1Checkin-Signature: sha256=<hex>, the HMAC-SHA256 of the raw request body, in either format. The Webhooks reference shows both payloads and every header.

Test sends and delivery history

Send test posts one test request to the webhook now, in its payload format and signed with its secret, with X-1Checkin-Event-Type: test. The result appears on the webhook and in its history, and a test is never retried.

Delivery history lists the webhook's deliveries, newest first: the state, the event, the check-in, the attempts, the last HTTP status or error, and the next retry. Deliveries are retried automatically, up to 8 attempts over about 42 minutes (see the retry policy). Finished deliveries stay in the history for 30 days, and an 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.

Disabling, changing and deleting

A disabled webhook receives nothing, and the deliveries that were waiting for it are not sent later. Changing a webhook's URL cancels the deliveries still waiting for the old URL, so an old payload never goes to a new address, and unsubscribing from an event cancels that event's waiting deliveries. Deleting a webhook cancels all of its waiting deliveries.

Webhooks other APIs also change

  • Account webhook (production): the webhook your account had before multiple webhooks were available. PUT /api/company/webhook changes it too.
  • Sandbox API settings (sandbox): POST /api/sandbox/v1/settings changes this webhook. push_api_status_url is its URL, push_api_enabled turns it on or off, push_api_headers are its custom headers, and push_api_request_enabled subscribes it to checkin.info_requested. It uses the Corp API format and is not signed until you rotate its secret in Settings.

A Z0 sandbox check-in created with its own webhook_url sends all of its events to that URL only, in the Corp API format, instead of to your sandbox webhooks.

Receiving webhooks

Build and secure your receiver with the setup guide:

Webhook Setup Guide