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 know when something happens in Synaptic, such as someone sending a message or adding a contact.

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 your app receives a webhook request from Synaptic, check the type attribute to see what event caused it. The first part of the event type will tell you the payload type, e.g., a conversation, message, etc.

Example webhook payload

{
  "id": "a056V7R7NmNRjl70",
  "type": "aircraft.arrived",
  "payload": {
    "id": "WAz8eIbvDR60rouK"
    // ...
  }
}

In the example above, a aircraft was seen as arrived, and the payload type is a aircraft.

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 payload

{
  "id": "a056V7R7NmNRjl70",
  "EventType": "AIRCRAFT.ARRIVED",
  "EventPayload": {
    "EventName": "AIRCRAFT.ARRIVED",
    "AirlineCode": "NK",
    "Station": "FLL",
    "Gate": "G13",
    "TailNumber": "NK34443",
    "ArrivalFlight#": "NK321",
    },
    "attachments": [],
    "read_at": 705103200,
    "created_at": 692233200,
    "updated_at": 692233200
  }
}

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. A postback User and password are optional parameters for basic authentication if the postback url requires them.

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

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

Parameters:
{
  "WebhookId": "a056V7R7NmNRjl70-123-456",
  "EventSubscriptionId": "abcdef-123-456",
}

Response

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

{
  "data": {
    "body": "Subscription deleted"
  }
}

GET/v2/webhooks/notifications

List Webhooks Events sent to User

This will return a list of all webhook notifications by WebhookID, as a query parameter, that a user is subscribed to. Provide optional parameters 'offset' and 'limit' to limit the number of notifications returned.

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": {
        "id": "a056V7R7NmNRjl70",
        "EventType": "AIRCRAFT.ARRIVED",
        "EventPayload": {
          "EventName": "AIRCRAFT.ARRIVED",
          "AirlineCode": "NK",
          "Station": "FLL",
          "Gate": "G13",
          "TailNumber": "NK34443",
          "ArrivalFlight#": "NK321",
          },
          "attachments": [],
          "read_at": 705103200,
          "created_at": 692233200,
          "updated_at": 692233200
        }
      },
      "EventResponse": {
        "status": "200",
        "message": "OK",
        "response": {
          // Response from the postback URL...
        }
      }
    },
    {
      "EventTypeId": "AIRCRAFT",
      "WebhookId": "a056V7R7NmNRjl70-123-456",
      "WebhookName": "Aircraft Departing",
      "WebhookUrlInfo": "Aircraft Departing Webhook",
    }
    ...
  ]
}