Working with cron job monitors in our API

We'll assume you've already got the API authentication settled and you have our API key with you (this is the Authorization header in all the examples used below).

Get all cron jobs for a website #

Cron job monitors are attached to a website in Oh Dear. To retrieve a list of monitored cron jobs, you'll the website ID first.

The /api/sites/{$siteId}/cron-checks endpoint lists all your cron job monitors for that particular site.

$ OHDEAR_TOKEN="your API token"
$ curl https://ohdear.app/api/sites/1/cron-checks \
    -H "Authorization: Bearer $OHDEAR_TOKEN" \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json'

As a result, you get the details for every cron job monitor attached to this site:

{
  "data": [
    {
      "id": 1,
      "uuid": "0d210b09",
      "name": "cronjob number one",
      "type": "simple",
      "description": "a description goes here",
      "frequency_in_minutes": 15,
      "grace_time_in_minutes": 5,
      "cron_expression": null,
      "server_timezone": "Europe/Brussels",
      "ping_url": "https://ping.ohdear.app/0d210b09",
      "created_at": "2020-07-28 13:27:02"
    },
    {
      "id": 2,
      "uuid": "8eb64808",
      "name": "cronjob number two",
      "type": "simple",
      "description": "a description goes here",
      "frequency_in_minutes": 60,
      "grace_time_in_minutes": 10,
      "cron_expression": null,
      "server_timezone": "Europe/Brussels",
      "ping_url": "https://ping.ohdear.app/8eb64808",
      "created_at": "2020-07-28 13:27:02"
    }
  ],
}

The response is a JSON encoded array with all the details of the cron jobs you defined to be monitored.

Create a simple cron job monitor #

You can create a new cron job monitor using our API. You'll need the site ID where you want to attach the new monitor to.

$ OHDEAR_TOKEN="your API token"
$ curl -X POST https://ohdear.app/api/sites/1/cron-checks \
    -H "Authorization: Bearer $OHDEAR_TOKEN" \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{
      "name": "your cron job name",
      "type": "simple",
      "frequency_in_minutes": 10,
      "grace_time_in_minutes": 15,
      "description": "a description goes here"
    }'

The example above will create a new cron job monitor by providing both the frequency and the gracetime. Note how the type is set to simple.

The response will include the Ping URL you can point your cron jobs to:

{
  "id": 12,
  "uuid": "ba4322cf",
  "name": "your cron job name",
  "type": "simple",
  "description": "a description goes here",
  "frequency_in_minutes": 10,
  "grace_time_in_minutes": 15,
  "cron_expression": "",
  "server_timezone": null,
  "ping_url": "https://ping.ohdear.app/ba4322cf",
  "created_at": "2020-08-03 12:18:33"
}

The ping_url should be used in your scripts to report back the status of your cron jobs to us.

Create a new cron job monitor via crontab expression #

Alternatively, you can create a new cron job monitor using the crontab expression as well.

Note how in this example the type is set to cron instead of simple.

$ OHDEAR_TOKEN="your API token"
$ curl -X POST https://ohdear.app/api/sites/1/cron-checks \
    -H "Authorization: Bearer $OHDEAR_TOKEN" \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{
      "name": "your cron job name",
      "type": "cron",
      "cron_expression":"* * * * *",
      "grace_time_in_minutes": 10,
      "description": "a description goes here",
      "server_timezone": "UTC"
    }'

The example above will create a new cron job monitor using the crontab expression * * * * * to indicate it should run every minute.

The response will include the Ping URL you can point your cron jobs to:

{
  "id": 10,
  "uuid": "19eea41a",
  "name": "your cron job name",
  "type": "cron",
  "description": "a description goes here",
  "frequency_in_minutes": 0,
  "grace_time_in_minutes": 10,
  "cron_expression": "* * * * *",
  "server_timezone": "UTC",
  "ping_url": "https://ping.ohdear.app/19eea41a",
  "created_at": "2020-08-03 12:13:53"
}

The ping_url should be used in your scripts to report back the status of your cron jobs to us.

Bulk cron job synchronization #

For our PHP-SDK, we've created a mass-update endpoint you can use to update all cron jobs for a single site. This will remove any cron job not explicitly in this sync API call, so it is a destructive action.

$ OHDEAR_TOKEN="your API token"
$ curl -X POST https://ohdear.app/api/sites/1/cron-checks/sync \
    -H "Authorization: Bearer $OHDEAR_TOKEN" \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{
        "cron_checks": [
          {
            "name": "cron job #1",
            "type": "cron",
            "cron_expression":"* * * * *",
            "grace_time_in_minutes": 10,
            "description": "description for cron #1",
            "server_timezone": "UTC"
          },
          {
            "name": "cron job #2",
            "type": "cron",
            "cron_expression":"* * * * *",
            "grace_time_in_minutes": 10,
            "description": "description for cron #2",
            "server_timezone": "UTC"
          }
        ]
    }'

The return data, if the API call was successful, is a confirmation of each cron job definition together with all its metadata.

[
  {
    "id": 9,
    "uuid": "c1803dce",
    "name": "cron job #1",
    "type": "cron",
    "description": "description for cron #1",
    "frequency_in_minutes": null,
    "grace_time_in_minutes": 10,
    "cron_expression": "* * * * *",
    "server_timezone": "UTC",
    "ping_url": "https://ping.ohdear.app/c1803dce",
    "created_at": "2020-09-03 19:20:25"
  },
  {
    "id": 10,
    "uuid": "40e8e39e",
    "name": "cron job #2",
    "type": "cron",
    "description": "description for cron #2",
    "frequency_in_minutes": null,
    "grace_time_in_minutes": 10,
    "cron_expression": "* * * * *",
    "server_timezone": "UTC",
    "ping_url": "https://ping.ohdear.app/40e8e39e",
    "created_at": "2020-09-03 19:20:25"
  }
]

Error handling #

If an error occured, you'll be given a non-HTTP/200 response code. The resulting payload might look like this.

{
  "message": "The given data was invalid.",
  "errors": {
    "name": [
      "There already exist a cron check with this name for this site."
    ]
  }
}

Was this page helpful to you? Feel free to reach out via support@ohdear.app or on Twitter via @OhDearApp if you have any other questions. We'd love to help!