Skip to main content

Triggers

A package runs in response to a trigger. There are five trigger types:

  • Webhooks: an external system (such as Xurrent) sends an HTTP request to the automator.
  • Schedule: a timer fires on a cron-like schedule.
  • Inbound email: a message arrives in a configured mailbox (IMAP or MS Graph).
  • Service GET: a GET request is made to a service endpoint.
  • Service POST: a POST request is made to a service endpoint.

Configuration of these trigger events is done in two steps:

  1. Configure the trigger itself: set up a webhook, schedule, service, or mailbox.
  2. Link the trigger to the package(s).

Webhooks are configured in the Webhooks tab (see below), inbound emails in the Inbound email configurations tab, schedules in the Schedules tab (see below), and services in the Services tab.

A single trigger can be linked to multiple packages, which gives you a powerful organization tool: rather than mixing logic for different types of integrations in a single package, you can cleanly separate them into separate packages. Conversely, a single package can be linked to multiple triggers, which allows you to reuse the same logic.

Relation to account​

When linking a trigger to a package, you always have to specify an account as well.

For webhooks, you specify the webhook and the account separately: the webhook determines which requests trigger the package, the account is the Xurrent account the package works with. The account also helps to identify the API user, as explained in the previous section.

For all trigger types (including webhooks), the account is used as the default account for the package execution. Many functions in the standard library have an optional account parameter, that takes the name of the account to use. One example of this is the http_request function, but almost all functions in the standard library that need to connect to a remote service have this. If the account parameter is not explicitly specified, the package execution will use the default account.

Apart from being shorter to write, this also makes it possible to use the same package for multiple accounts. For example, suppose you have a Xurrent-to-Xurrent integration that you want to run in multiple Xurrent support domains. To avoid duplicating the integration logic, you could create a single package and link a trigger for each Xurrent support domain.

Webhook configuration​

A webhook is an inbound HTTP endpoint. Its URL has the form https://<automator host>/webhook/<profile>/<environment>/<identifier>.

A webhook has a webhook type:

  • Xurrent: used for webhooks sent by Xurrent.
  • Generic: used for any other external system.

For Xurrent webhooks, the automator supports JWT authentication (see below) and automatically handles verification. In addition, you can specify which Xurrent events trigger a package, for more fine-grained control over when a package is executed.

info

Xurrent events on record types with a high rate of change, such as request.update, can lead to many unnecessary package executions. We recommend using the automation_rule event instead. Create an automation rule in Xurrent that calls a webhook endpoint at the automator when specific preconditions are met.

Authentication​

Generic webhooks always use HTTP basic authentication.

Xurrent webhooks support three methods:

  • HTTP basic authentication: click Create webhook URL to generate a username and password. The URLs with the credentials are shown once; configure one of them as the webhook URL in the external system.
  • JWT, policy based authorization using manually configured public key: the requests carry a JWT that is signed by a webhook policy in Xurrent. Paste the public key of the policy, set the audience field, and (optionally) specify the used encryption algorithm and the issuer.
  • JWT, policy based authorization using OpenID Connect discovery: same as the above, but the automator retrieves the public keys of the policy from Xurrent, so no key has to be pasted. Keys rotated in Xurrent are picked up automatically.

For the JWT methods, the automator also checks the issuer of the token. If you leave it empty, the issuer is determined on first use: the first token that is signed by a policy on a Xurrent domain pins its issuer to the webhook, and from then on only tokens from that issuer are accepted.

Scheduler configuration​

Scheduler configuration follows cron syntax. It consists of five space-separated parts:

*    *    *    *    *
┬    ┬    ┬    ┬    ┬
│    │    │    │    │
│    │    │    │    └ day of week (0 - 7) (0 or 7 is Sun)
│    │    │    └───── month (1 - 12)
│    │    └────────── day of month (1 - 31)
│    └─────────────── hour (0 - 23)
└──────────────────── minute (0 - 59)

Examples:

* * * * *           -> Every minute, every hour, every day
0 0 * * *           -> Every day at 00:00
5 * * * *           -> Every hour, 5 minutes past the full hour
*/5 * * * *         -> Every 5 minutes
20,30 1 * * 1-5     -> Monday to Friday at 01:20 and 01:30
8,12,17 * * 1,3,5   -> At 08:00, 12:00 and 17:00 on Monday, Wednesday and Friday