Webhook setup

You will need the following information ready:

1. webhookTypeId: the id of a Webhook Type. This defines the circumstances that trigger the Webhook (e.g. "Account Created").
2. query: a GraphQL query. It accepts a $objectid: ID! variable which will be set to the ID of the object that triggered the webhook.
3. url: the external service endpoint that will be hit by a HTTP POST request with the result of the query:
   • Always use HTTPS to ensure your data is encrypted in transit.
   • We recommend using basic authentication to limit access to the endpoints, but this is optional, e.g. https://username:password@www.somedomain.com/hook/1
   • For testing purposes, Webhooks.site is a useful free 3rd Party tool.
   • It's best practice to segment the endpoint by type for debugging and error monitoring.
4. notificationEmails: a list of email addresses to be notified if the webhook execution fails.
5. name: is an arbitrary name for the webhook that should identify its purpose.
6. config (optional): this is a free-form JSON payload which can be delivered as part of the Webhook's contents. This will allow you to provide a secret so you can verify a payload came from Administrate. This data is encrypted at rest, cannot be queried and is not exposed anywhere in our platform.
7. filterExpression (optional): a JMESPath expression that is executed on the query results and will determine if the webhook fires. This is useful to limit applicability of the webhook to payloads that match specific criteria (more information)

Create new webhook

The following mutation creates a new "Event Updated" webhook providing the minimal information

mutation {
  webhooks{
    create(input:{
      webhookTypeId: "V2ViaG9va1R5cGU6ZXZlbnRfdXBkYXRlZA=="
      name: "Event Updated"
      query: "query test($objectid: ID!){ node(id: $objectid) { id ... on Event{ code }}}"
      url: "https://test.example.com"
      notificationEmails: ["test@example.com"]
    }) {
      webhook{
        id
        lifecycleState
      }
      errors{
        label
        message
        value
      }
    }
  }
}

The response contains the new Webhook ID which is inactive by default:

{
  "data": {
    "webhooks": {
      "create": {
        "webhook": {
          "id": "T3V0Ym91bmRIb29rOjM=",
          "lifecycleState": "inactive"
        },
        "errors": []
      }
    }
  }
}

Update

Webhooks can be updated to change their name, query, url, configuration or to activate, disable and deactivate them. See our WebhookCreateInput API reference for the available options.

New webhooks are inactive by default. This means that events will not fire and the url specified will not be hit.

Webhooks can be in 3 lifecycle states:

• active: the webhook fires when applicable events occur and hits the url specified
• disabled: the webhook fires and logs the generated payload, but does not hit the url
• inactive: the webhook does not fire, does not log any events and does not hit the url

Activate a Webhook

To activate a webhook:

mutation activate{
  webhooks{
    update(input:{
      webhookId: "T3V0Ym91bmRIb29rOjM="
      lifecycleState: active
    }) {
      webhook{
        id
        lifecycleState
      }
      errors{
        label
        message
        value
      }
    }
  }
}

Disable a Webhook

A disabled Webhook will still record applicable events, log them and generate the corresponding payload from the query, but they will not call the external URL with the payload.

To disable a webhook:

mutation disable{
  webhooks{
    update(input:{
      webhookId: "T3V0Ym91bmRIb29rOjM="
      lifecycleState: disabled
    }) {
      webhook{
        id
        lifecycleState
      }
      errors{
        label
        message
        value
      }
    }
  }
}

When an event is updated in the TMS, this webhook will hit the

List configured Webhooks

The following fetches the first page of configured automatic Webhooks. It is not possible to query the config object, as it is encrypted sensitive data, but it's possible to query whether a value is set for the field:

query {
  webhooks(filters:[
    {field: typeTrigger, operation: eq, value: "automatic"}
  ]){
    edges{
      node{
        id
        name
        lifecycleState
        webhookType{
          name
        }
        query
        url
        hasConfigSet
      }
    }
  }
}

See the WebhookField API Reference for the filtering options available.

Example payload

Once the Webhook is setup and active, performing the associated event will see the url specified hit by the following example payload where

• metadata contains some basic information about which Webhook ID triggered the event, the instance and time
• payload contains the result of executing the query on the object ID that triggered the Webhook
• configuration contains the data provided in the config field when creating or updating the Webhook, or null if not set.

{
  "metadata": {
    "user": {
      "email": null
    },
    "instance": "https://myinstance.administrateapp.com",
    "triggered_at": "2023-04-04T11:23:16.000000Z",
    "context": "graphql",
    "webhook_id": "T3V0Ym91bmRIb29rOjYx",
    "is_retry": false
  },
  "payload": {
    "node": {
      "id": "Q291cnNlOjI=",
      "code": "REACT1"
    }
  },
  "configuration": null
}