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, together with its latest status:

{
  "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",
      "latest_result": "pingFinished",
      "latest_ping_at": "2020-11-16 09:19:40"
    },
    {
      "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",
      "latest_result": "pingFinished",
      "latest_ping_at": "2020-11-16 09:19:40"
    }
  ],
}

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

Result types #

The latest_result response in the API can be one of the following values.

These are values actively submitted by your application to your cron monitoring URL endpoint:

  • pingStarting: we have received the "started" pingback from your application
  • pingFinished: we have received the "finished" pingback from your application, indicating no errors occurred
  • pingFailed: we have received the "failed" pingback from your application, indicating errors have occured

These are values we may have detected ourselves, without active participation from your application:

  • checkRanTooLate: because we did not receive a new ping URL on time, we have marked the cron task as failed because it ran too late
  • sentCronNotExutedOnTimeNotification: because the check didn't execute on time, we have sent the "did not run on time" notification
  • sentPingFailedNotification: your application reported us that the last ping contained a failure, we have now sent a notification that the ping failed

The success states of a cronjob are determined only by the pingFinished result. All other types indicate that we are either waiting on a ping, have received a failed ping, or have received no ping at all.

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",
    "latest_result": "pingFinished",
    "latest_ping_at": "2020-11-16 09:19:40"
  },
  {
    "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",
    "latest_result": "pingFinished",
    "latest_ping_at": "2020-11-16 09:19:40"
  }
]

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!