Sending Check-ins via the AppSignal API

You can report check-ins to AppSignal via POST requests to the AppSignal API, for example, via cURL.

This section will cover how to send check-ins via URL params or a NDJSON payload.

We advise reading our terminology explainer below before setting up your check-in API requests.

Check-in terminology explained

In this documentation, we will refer to requests that start a check-in and finish a check-in. This documentation section outlines what these terms mean and their practical use cases.

Start Check-in

Start check-ins inform AppSignal of when a check-in's occurrence begins. Start Check-ins are optional; however, we recommend using them if you'd like insights into job execution times.

Start Check-ins require you to define the kind attribute in your URL parameters or request NDJSON. If the kind value is nil or has a value other than start, the check-in will be treated as a Finish Check-in.

Finish Check-in

Finish Check-ins inform AppSignal that the check-in's occurrence ends. Unlike Start Check-ins, you do not have to provide AppSignal with a kind attribute. AppSignal treats all check-ins that do not have a kind attribute of start as Finish check-ins.

1. Create a check-in in AppSignal

Follow our Check-in creation instructions to create a new check-in. Ensure the check-in crontab schedule matches the job you are monitoring.

Take note of the check-in identifier, as this will be needed in API requests.

2. Authenticate requests

You can authenticate your requests using URL parameters with your app-level API key. This differs from your organization-level key and can be found in your app's Push & deploy settings.

https://appsignal-endpoint.net/check_ins/cron?api_key=your-app-level-api-key
 

3. Send check-ins using URL parameters

To send check-ins using URL params, you must post check-in data to the following URL:

https://appsignal-endpoint.net/check_ins/cron
 

URL params

1. Send Start Check-in

Starting a check-in is optional. For a minimal integration, you only need to send Finish Check-ins; however, if you wish to measure your job duration, Start Check-ins are required.

Ensure you POST the start request at the beginning of your background job.

To start a check-in, you must ensure we include the optional kind parameter with a value of start. To start a check-in with only the required parameters, we'd make the following request:

https://appsignal-endpoint.net/check_ins/cron?api_key=your-app-level-api-key&identifier=your-check-in-identifier&kind=Start
 

If we want to start a check-in and include all optional data, we'd make the following request:

https://appsignal-endpoint.net/check_ins/cron?api_key=your-app-level-api-key&identifier=your-check-in-identifier&timetamp=your-check-in-utc-timestamp&kind=Start&digest=your-check-in-id
 

Example cURL request

curl -X \
POST 'https://appsignal-endpoint.net/check_ins/cron?api_key=your-app-level-api-key&identifier=your-check-in-identifier&timetamp=your-check-in-utc-timestamp&kind=Start&digest=your-check-in-id'

2. Send Finish Check-in

Ensure you POST the finish request at the end of your background job.

Note that the kind parameter is optional. If you do not define this parameter in your API request, the request will automatically be handled as a finish request.

To end a check-in using only the required params:

https://appsignal-endpoint.net/check_ins/cron?api_key=your-app-level-api-key&identifier=your-check-in-identifier

To end a check-in using all optional parameters, we'd make the following request:

https://appsignal-endpoint.net/check_ins/cron?api_key=your-app-level-api-key&identifier=your-check-in-identifier&timetamp=your-check-in-utc-timestamp&kind=finish&digest=your-check-in-id

Example cURL request

curl -X \
POST 'https://appsignal-endpoint.net/check_ins/cron?api_key=your-app-level-api-key&identifier=your-check-in-identifier&timetamp=your-check-in-utc-timestamp&kind=finish&digest=your-check-in-id'

3. Send check-ins using NDJSON

To send check-ins using NDJSON, you must post check-in data to the following URL:

https://appsignal-endpoint.net/check_ins/json

Remember to authenticate your request.

NDJSON variables

Below are the optional and required NDJSON variables for creating a check-in.

1. Send Start Check-in

Sending a Start Check-in is optional, for a minimal integration you only need to send a Finish Check-in at the end of your job, however, if you wish to measure your job duration Start Check-ins are required.

To send a Start Check-in, include the start variable in your request's NDJSON payload. Below is an example using the minimal required check-in data:

{"check_in_type": "cron", "identifier": "your-check-in-identifier", "kind": "start"}

Below is an example including all additional optional data:

{"check_in_type": "cron",  "identifier": "your-check-in-identifier", "kind": "start", "timestamp": utc-timestamp, "id": "your-check-ins-id"}

Example cURL request

curl -X \
POST -H \
 "Content-type: application/json" -d '{"check_in_type": "cron",  "identifier": "your-check-in-identifier","kind": "start","timestamp": utc-timestamp, "id": "your-check-ins-id"}' 'https://appsignal-endpoint.net/check-ins/json'

2. Send Finish Check-in

You can send a finish check-in by omitting the kind variable or defining it as finish.

Below is an example of a Finish Check-in using the minimal data required:

{"check_in_type": "cron",  "identifier": "your-check-in-identifier"}

Below is an example including all additional optional data:

{"check_in_type": "cron", "identifier": "your-check-in-identifier", "kind": "finish", "timestamp": utc-timestamp, "id": "your-check-ins-id"}

Example cURL request

curl -X \
POST -H \
 "Content-type: application/json" -d '{"check_in_type": "cron",  "identifier": "your-check-in-identifier", "kind": "finish", "timestamp": utc-timestamp, "id": "your-check-ins-id"}' 'https://appsignal-endpoint.net/check-ins/json?api_key=your-app-level-api-key'

Sending multiple check-ins in one payload

You can send multiple check-ins in a single payload with NDJSON.

Our HTTP-JSON endpoint expects check-ins to be sent in an NDJSON format to our endpoint. NDJSON stands for Newline Delimited JSON, which means that each log line is its own JSON object, below is an example of how a payload including multiple check-ins could look:

{"check_in_type": "cron", "identifier": "example-check-in", "kind": "start", "timestamp": utc-start-timestamp, "id": "EHB123"}
{"check_in_type": "cron", "identifier": "example-check-in", "kind": "finish", "timestamp": utc-end-timestamp, "id": "EHB123"}

Example cURL request

curl -X \
POST -H \
 "Content-type: application/x-ndjson" \
 -d '{"check_in_type": "cron", "identifier": "example-check-in", "kind": "start", "timestamp": utc-start-timestamp, "id": "EHB123"}
{"check_in_type": "cron", "identifier": "example-check-in", "kind": "finish", "timestamp": utc-end-timestamp, "id": "EHB123"}' \
 'https://appsignal-endpoint.net/check-ins/json?api_key=your-app-level-api-key'

4. Reviewing Check-in occurrences in AppSignal

Once configured AppSignal will begin to display occurrence information for your check-ins.

You can read more about occurrences in our Check-in Occurrences documentation.