Skip to main content

Subscription notifications via webhooks

This subscription method will push notifications about subscribed events to a specified URL.

Webhook creation​

In order to start subscription that will use this notification method you have to save necessary webhook data using a mutation in our API. Mutations for creating and deleting this data can be found in our documentation portal.

To register webhook you need to provide following data.

  • label is a unique identifier for registered webhook (must be more than 5 characters),
  • refreshToken is used to resolve subscriptions. Each used refresh token is valid for 30 days and its validity is extended by another 30 days on access token generation.
  • webhookUrl is URL address that will be called with subscription data when subscribed event occurs,
  • subscription is a string containing a valid GraphQL subscription,
  • variables is a JSON with variables for subscription.

You can have at most 10 webhooks per refresh token registered at any given time.

For a detailed reference of what triggers each subscription, see Available subscriptions and their triggers.

Important: variables must use GraphQL variable syntax​

The subscription field must declare all dynamic values as GraphQL variables (using $variableName: Type syntax in the operation signature). Do not hardcode values inline in the query string — they will not be substituted at execution time, which may cause the subscription to fail and no notification to be sent.

Incorrect — will not work​
subscription: "subscription { trip { tripStatusChanged(operatorId: \"MAN\") { nid status } } }"
Correct​
subscription: "subscription TripStatus($operatorId: ID!) { trip { tripStatusChanged(operatorId: $operatorId) { nid status } } }"
variables: "{\"operatorId\": \"MAN\"}"
Examples​

You can find an example of mutation creating a new webhook below.

mutation {
  webhook {
    createSubscriptionWebhook(
      refreshToken: "<refreshToken>",
      label: "TEST1",
      subscription: "subscription Sub($txt: String!) { echo(text: $txt) }",
      variables: "{\"txt\": \"ABC\"}",
      webhookUrl: "<url>"
    ) {
      ... on CreateSubscriptionWebhookViolationList {
        error: value {
          message
          path
        }
      }
      ... on NonNullBooleanValue {
        result: value
      }
    }
  }
}

Above will subscribe to a test echo subscription. You can test it by invoking a mutation that will push an event triggering this subscription. Upon invoking this mutation your webhook should be triggered with "ABC111" as payload.

mutation {
  echoSubscription(text: "111")
}

Webhook deletion​

In order to delete an existing webhook you can use an deleteSubscriptionWebhook mutation described in can be found in our documentation portal.

mutation {
  webhook {
    deleteSubscriptionWebhook(label: "TEST1")
  }
}

Notification format and authentication​

Notifications from Leon will be sent as POST requests to URL specified during webhook creation. Notification data is dependent on registered GraphQL subscription and will be contained as JSON in request body.

Valid notifications from Leon will also include an Authorization header containing JWT token that should be a decrypted and validated to ensure security. JWT in this header will contain following data.

  • iat is a timestamp at which token was issued,
  • exp is a token expiry timestamp,
  • jti is an unique token identifier,
  • iss (token issuer) must be equal to Leon Software,
  • aud (token audience) must be equal to URL specified during webhook creation.

Authorization token is signed using RS512 algorithm. To verify the signature you can use a public key available under following URL https://{oprId}.leon.aero/.well-known/keys/leon-subscriptions-webhook-1.pub where oprId is your operator code.

You can find more information about JWT tokens as well as a list of libraries you can use to handle JWT token authorization here.

Available subscriptions​

You can find a list of available subscriptions in our documentation portal.