Subscribe to Webhooks

You can subscribe to a webhook using the Nautical API or through the Dashboard. This article will walk you through using the API.

Create a custom app

Webhooks are added under apps in your marketplace. Configuring a webhook begins with creating a custom app with the proper permissions.

See Manage Custom Apps for more information.

Create a webhook

For example, let’s say you want to measure the drop-off at checkout. You would need to receive notifications from your webhook app when a customer enters the checkout process and when an order is created.

Use the webhookCreate mutation to add a webhook.

The mutation.webhookCreate takes the following inputs:

• name: A name to identify the webhook.
• targetUrl: The URL to receive the payload.
• events: The events that webhook wants to subscribe to. A list of events can be found in the WebhookEventTypeEnum API reference.
• app: The id of the app to which the webhook belongs.
• isActive: Whether to activate the webhook.
• secretKey: (Optional) This key is used to create a hash signature for each webhook payload. Nautical generates an HMAC SHA256 header using the provided secret key and the payload body. The secret key is sent in the x-nautical-signature HTTP header.

To get the App ID, we can run the apps query:

Mutation

query {
    apps(first: 100) {
      edges {
        node {
          id
          name
        }
      }
   }
}

Now we can run the webhookCreate mutation:

Mutation

mutation {
  webhookCreate(
    input: {
      name: "Checkout drop-off"
      targetUrl: "https://checkout-drop-off.example.com"
      events: [CHECKOUT_CREATED, ORDER_CREATED]
      app: "QXBwPkj="
      isActive: true
      secretKey: "secret-key"
    }
  ) {
    webhook {
      id
    }
    webhookErrors {
      field
      code
    }
  }
}

Show more ↓

Update and delete webhooks

To manage the webhooks you will use mutation.webhookDelete and mutation.webhookUpdate.

Query webhooks

To get the webhook ID needed for these mutations, you can request webhooks information with the apps query.

For example, the following query returns the first 15 apps and their webhooks:

Query

query {
  apps(first: 15) {
    edges {
      node {
        id
        name
        webhooks {
          id
          name
          events {
            eventType
          }
          isActive
        }
      }
    }
  }
}

Update a webhook

Update the fields under a webhook using the webhookUpdate mutation:

Mutation

mutation {
  webhookUpdate(id: "QXBwPkj=", input: { isActive: false }) {
    webhook {
      isActive
    }
    webhookErrors {
      field
      code
    }
  }
}

Delete a webhook

Delete a webhook using the webhookDelete mutation:

Mutation

mutation {
  webhookDelete(id: "QXBwPkj=") {
    webhookErrors {
      field
      code
    }
  }
}