Skip to content

Quickstart: create a webhook

Get an HTTP callback whenever a Skedulo record changes, defined as a GraphQL subscription, created with one API call.

Webhooks call an endpoint you control whenever records change in Skedulo: a job is created, a status moves, a booking is cancelled. Each webhook is a GraphQL subscription that declares which object, which operations, and which fields you care about.

Before you start

You need:

  • An API token with administrator access.
  • An HTTPS endpoint that can receive POST requests. For a first test, a request-inspection service (or a tunnel to a local server) works fine.

1. Define the webhook

A webhook is a name, a destination URL, and a GraphQL subscription. Save this as webhook.json:

{
  "name": "job-changes",
  "url": "https://your-secure-endpoint.com",
  "type": "graphql",
  "query": "subscription { schemaJobs { operation timestamp data { UID Duration } previous { Duration } } }"
}

Reading the subscription:

  • schemaJobs: subscribe to changes on the Jobs object. Every standard and custom object has a corresponding schema<Object> subscription field.
  • operation: which change fired (INSERT, UPDATE, or DELETE).
  • data: the record's current values. A webhook fires only when one of the fields in the data block changes.
  • previous: the same fields' values before the change.

2. Create it

curl -s -X POST -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" -d @webhook.json \
  'https://api.skedulo.com/webhooks' | jq

3. Trigger and inspect

Change a job in your tenant (edit its duration, for example). Skedulo POSTs to your endpoint with a body matching your subscription's shape, plus skedulo-webhook-id and skedulo-request-id headers for correlation.

Filtering and configuration

  • Narrow which changes fire the webhook with filter (and extendedFilter) arguments on the subscription field, using the same syntax as query filters.
  • Keep secrets out of definitions with config variables: {{ CONFIG_VAR_NAME }} templates in the url and headers fields resolve at delivery time. An unresolved variable fails the webhook, so define variables before referencing them.
  • Custom objects need change-tracking enabled to fire webhooks (enabled automatically for objects created after May 2024).

Prefer the CLI?

Webhooks are artifacts, so you can manage them in source control and deploy with the Skedulo CLI:

sked artifacts webhook upsert -f my-webhook.webhook.json -a <tenant-alias>

Example webhook definitions (alongside every other artifact type) are in the CLI examples repository.

Next steps