Webhooks

In this guide, we will look at how to register and consume webhooks to integrate your app with Synaptic. With webhooks, your app can receive operational events—aircraft movement, ground equipment sightings, jet bridge status, and more—as they occur.

Subscribing to webhooks

To subscribed to a new webhook, you need to have a URL in your app that Synaptic can call. You can configure a new webhook from the Synaptic dashboard under API settings or continue reading to subscribe directly through the API. Select an existing webhook by picking the events you want to listen for, and add your URL.

Now, whenever something of interest happens in your app, a webhook is fired off by Synaptic. In the next section, we'll look at how to consume webhooks.

Consuming webhooks

When Synaptic POSTs to your postback URL, the body is a single JSON object. Event details live in payload (the EventPayload from the event producer). Use Summary for the event name; type is always "message". An optional Adaptive Card (Microsoft Teams format 1.5) is included in attachments for clients that render cards.

If the subscription was created with postback credentials, Synaptic sends HTTP Basic authentication using the configured username and password (PostbackUser / PostbackPassword on subscribe; stored server-side as EventPostbackUser / EventPostbackPassword).

Outbound request body

{
  "payload": {
    "EventName": "AIRCRAFT.ARRIVED",
    "AirlineCode": "AA",
    "Gate": "B12",
    "Station": "DFW",
    "ArrivalFlight#": "AA1234",
    "DepartureFlight#": "AA5678",
    "TailNumber": "N12345",
    "EventDateTimeFirstSeen": "2026-05-21T10:00:00Z",
    "EventDateTimeLastSeen": "2026-05-21T10:15:00Z",
    "MediaUrl": "https://example.com/video.mp4"
  },
  "Summary": "AIRCRAFT.ARRIVED",
  "type": "message",
  "attachments": [
    {
      "contentType": "application/vnd.microsoft.card.adaptive",
      "contentUrl": null,
      "content": { }
    }
  ],
  "webhookId": "a056V7R7NmNRjl70-123-456",
  "webhookEventId": "550e8400-e29b-41d4-a716-446655440000",
  "eventNotificationId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8"
}

The attachments[0].content object is an Adaptive Card built from the same EventPayload (gate, flights, tail, timestamps, optional media link). Integrations that only need structured data can read payload and ignore attachments.

eventNotificationId is generated once per subscriber delivery (before the POST is sent) and is stable for the notification record whether your endpoint returns success or failure. Use it with Get notification by ID to fetch delivery metadata later. webhookEventId identifies the persisted webhook event; use Get webhook event by ID when you need the shared event record. webhookId is the subscription's webhook definition.

Top-level fields

  • Name
    payload
    Type
    object
    Description

    The EventPayload as produced by the event pipeline. Additional keys may be present and are passed through unchanged.

  • Name
    Summary
    Type
    string
    Description

    Human-readable event name (matches EventName in the payload).

  • Name
    type
    Type
    string
    Description

    Always "message" for outbound webhook deliveries.

  • Name
    attachments
    Type
    array
    Description

    Typically one Adaptive Card (contentType: application/vnd.microsoft.card.adaptive). contentUrl is null; card JSON is in content.

  • Name
    webhookId
    Type
    string
    Description

    The WebhookId for this subscription (same value passed when subscribing).

  • Name
    webhookEventId
    Type
    string
    Description

    EventId from the persisted WebhookEvent row for this firing.

  • Name
    eventNotificationId
    Type
    string
    Description

    UUID for this subscriber delivery. Created before the outbound POST and reused when the notification is stored.

Subscriber flow

  1. Your postback URL receives the outbound POST.
  2. Read eventNotificationId, webhookEventId, and webhookId from the body (along with payload / Summary as needed).
  3. To reconcile or audit a delivery, call the lookup endpoints with the same Bearer JWT used for subscriptions (EventSubscriberId must match the JWT email).
  4. Alternatively, list notifications with ?WebhookId= as before.

Missing records and unauthorized access both return 404 (the events lookup does not return a separate 403, to avoid leaking whether an ID exists).

EventPayload fields

These fields drive subscription filtering and the adaptive card. Synaptic may include other keys in payload; only the fields below are interpreted for access control and card rendering.

  • Name
    EventName
    Type
    string
    Description

    Event identifier (e.g. AIRCRAFT.ARRIVED). Matches the top-level Summary field.

  • Name
    AirlineCode
    Type
    string
    Description

    Matched against the subscriber's airline access. Shown on the card when present.

  • Name
    Gate
    Type
    string
    Description

    Matched against the subscriber's gate access. Shown on the card.

  • Name
    Station
    Type
    string
    Description

    Matched against the subscriber's location access. Shown on the card as "Station".

  • Name
    ArrivalFlight#
    Type
    string
    Description

    Shown on the card as "Arr Flt#". The property name includes #.

  • Name
    DepartureFlight#
    Type
    string
    Description

    Shown on the card as "Dep Flt#".

  • Name
    TailNumber
    Type
    string
    Description

    Shown on the card.

  • Name
    EventDateTimeFirstSeen
    Type
    string
    Description

    ISO 8601 timestamp. Card label depends on event (see below).

  • Name
    EventDateTimeLastSeen
    Type
    string
    Description

    ISO 8601 timestamp. Card label depends on event (see below).

  • Name
    MediaUrl
    Type
    string
    Description

    When non-empty, the adaptive card includes a "View Media" action pointing to this URL.

Timestamp labels on the adaptive card:

  • POBT events: "Scheduled Departure" / "POBT"
  • Baggage events: "First Bag Seen" / "Last Bag Seen"
  • All other events: "Time First Seen" / "Time Last Seen"

Example EventPayload (illustrative)

{
  "AirlineCode": "AA",
  "Gate": "B12",
  "Station": "DFW",
  "ArrivalFlight#": "AA1234",
  "DepartureFlight#": "AA5678",
  "TailNumber": "N12345",
  "EventDateTimeFirstSeen": "2026-05-21T10:00:00Z",
  "EventDateTimeLastSeen": "2026-05-21T10:15:00Z",
  "MediaUrl": "https://example.com/video.mp4"
}

Actual keys and values depend on the event producer and event type.

See all event types

Event types

  • Name
    aircraft.arrived
    Type
    Description

    Aircraft Arrival seen.

  • Name
    aircraft.stationary
    Type
    Description

    Aircraft is Stationary.

  • Name
    aircraft.departed
    Type
    Description

    Aicraft Departure seen.

  • Name
    beltloaded.seen
    Type
    Description

    Belt Loader last seen.

  • Name
    fuelhouse.seen
    Type
    Description

    Fuel House last seen.

  • Name
    cateringtruck.seen
    Type
    Description

    Catering Truck last seen.

  • Name
    gpu.seen
    Type
    Description

    Ground Power Unit last seen.

  • Name
    pca.seen
    Type
    Description

    PCA last seen.

  • Name
    chocks.seen
    Type
    Description

    Chocks last seen.

  • Name
    jetbridge.connected
    Type
    Description

    Jet Bridge was connected.

Example outbound body

{
  "payload": {
    "EventName": "AIRCRAFT.ARRIVED",
    "AirlineCode": "NK",
    "Station": "FLL",
    "Gate": "G13",
    "TailNumber": "NK34443",
    "ArrivalFlight#": "NK321",
    "EventDateTimeFirstSeen": "2026-05-21T10:00:00Z",
    "EventDateTimeLastSeen": "2026-05-21T10:15:00Z",
    "MediaUrl": ""
  },
  "Summary": "AIRCRAFT.ARRIVED",
  "type": "message",
  "attachments": [
    {
      "contentType": "application/vnd.microsoft.card.adaptive",
      "contentUrl": null,
      "content": { }
    }
  ],
  "webhookId": "a056V7R7NmNRjl70-123-456",
  "webhookEventId": "550e8400-e29b-41d4-a716-446655440000",
  "eventNotificationId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8"
}
GET/v2/webhooks

Listing Available Webhooks

This will return a list of all available webhooks that can be subscribed to as a user. Provide optional parameters 'offset' and 'limit' to limit the number of webhooks returned.

Request

GET /v2/webhooks?offset=0&limit=10
HTTP/1.1 200 OK
Host: api.synaptic.com
Authorization: Bearer YOUR_JWT_TOKEN

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": [
    {
      "EventTypeId": "AIRCRAFT",
      "WebhookId": "a056V7R7NmNRjl70-123-456",
      "WebhookName": "Aircraft Arriving",
      "WebhookUrlInfo": "Aircraft Arriving Webhook",
    },
    {
      "EventTypeId": "AIRCRAFT",
      "WebhookId": "a056V7R7NmNRjl70-123-456",
      "WebhookName": "Aircraft Departing",
      "WebhookUrlInfo": "Aircraft Departing Webhook",
    }
    ...
  ]
}
POST/v2/webhooks/subscribe

Subscribing to Webhooks

To subscribe to a webhook, each webhook requires the email address of an authenticated Synaptic user and a postback URL for the webhook event to be sent as well as the ID of a webhook. Optional PostbackUser and PostbackPassword enable HTTP Basic auth on each outbound POST (see Consuming webhooks).

Request

POST /v2/webhooks/subscribe HTTP/1.1
Host: api.synaptic.com
Authorization: Bearer YOUR_JWT_TOKEN
Content-Type: application/json

Parameters:
{
  "WebhookId": "a056V7R7NmNRjl70-123-456",
  "EventSubscriberId": "your@email.com",
  "PostbackUrl": "https://yourapp.com/webhook",
  "PostbackUser": "username",
  "PostbackPassword": "password"
}

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": {
    "EventSubscriptionId": "abcdef-123-456",
    "WebhookId": "a056V7R7NmNRjl70-123-456",
    "EventSubscriberId": "your@email.com,
    "PostbackUrl": "https://yourapp.com/webhook",
    "PostbackUser": "username",
    "PostbackPassword": "password"
  }
}
DELETE/v2/webhooks/unsubscribe?EventSubscriptionId=abc-1234-5678

Unsubscribing from Webhooks

To unsubscribe from a webhook, each webhook requires the EventSubscriptionId from a successful response when subscribing.

Request

DELETE /v2/webhooks/unsubscribe HTTP/1.1
Host: api.synaptic.com
Authorization: Bearer YOUR_JWT_TOKEN
Content-Type: application/json

Query Parameters:
{
  "EventSubscriptionId": "abcdef-123-456",
}

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": {
    "body": "Subscription deleted"
  }
}
GET/v2/webhooks/events/:webhookEventId

Get webhook event by ID

Returns a single persisted webhook event by webhookEventId (the webhookEventId / EventId value on outbound deliveries).

Authorization: Bearer JWT. The caller must be subscribed to the event's WebhookId, or be an admin.

Request

GET /v2/webhooks/events/550e8400-e29b-41d4-a716-446655440000 HTTP/1.1
Host: api.synaptic.com
Authorization: Bearer YOUR_JWT_TOKEN

Returns 404 when the event is missing or the caller is not allowed (no separate 403).

GET/v2/webhooks/notifications/:eventNotificationId

Get notification by ID

Returns a single delivery notification by eventNotificationId (the UUID sent on each outbound POST).

Authorization: Bearer JWT. The notification row must belong to the JWT email (EventSubscriberId), or the caller must be an admin.

Request

GET /v2/webhooks/notifications/6ba7b810-9dad-11d1-80b4-00c04fd430c8 HTTP/1.1
Host: api.synaptic.com
Authorization: Bearer YOUR_JWT_TOKEN

Returns 404 when the notification is missing or the caller is not allowed.

GET/v2/webhooks/notifications

List webhook notifications

Returns webhook notifications for a subscribed user, filtered by WebhookId. Provide optional offset and limit query parameters. For a single delivery, prefer Get notification by ID using eventNotificationId from the outbound POST.

Request

GET /v2/webhooks/notifications?WebhookId=a056V7R7NmNRjl70-123-456&offset=0&limit=10
HTTP/1.1 200 OK
Host: api.synaptic.com
Authorization: Bearer YOUR_JWT_TOKEN
Content-Type: application/json

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": [
    {
      "EventNotificationId": "abcdef-123-456-xyz",
      "EventId": "a056V7R7NmNRjl70",
      "EventSubscriptionId": "abcdef-123-456",
      "EventRequest": {
        "payload": {
          "EventName": "AIRCRAFT.ARRIVED",
          "AirlineCode": "NK",
          "Station": "FLL",
          "Gate": "G13",
          "TailNumber": "NK34443",
          "ArrivalFlight#": "NK321",
          "EventDateTimeFirstSeen": "2026-05-21T10:00:00Z",
          "EventDateTimeLastSeen": "2026-05-21T10:15:00Z"
        },
        "Summary": "AIRCRAFT.ARRIVED",
        "type": "message",
        "attachments": [
          {
            "contentType": "application/vnd.microsoft.card.adaptive",
            "contentUrl": null,
            "content": { }
          }
        ],
        "webhookId": "a056V7R7NmNRjl70-123-456",
        "webhookEventId": "550e8400-e29b-41d4-a716-446655440000",
        "eventNotificationId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8"
      },
      "EventResponse": {
        "status": "200",
        "message": "OK",
        "response": {
          // Response from the postback URL...
        }
      }
    },
    {
      "EventTypeId": "AIRCRAFT",
      "WebhookId": "a056V7R7NmNRjl70-123-456",
      "WebhookName": "Aircraft Departing",
      "WebhookUrlInfo": "Aircraft Departing Webhook",
    }
    ...
  ]
}