Sending Heartbeats via the AppSignal API

You can report heartbeats to AppSignal via POST requests to the AppSignal API, for example via cURL.

This section will cover how to send heartbeats via URL params or a NDJSON payload.

We advise reading our terminology explainer below before setting up your heartbeat API requests.

Heartbeat terminology explained

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

Start Heartbeat

Start heartbeats inform AppSignal of when a heartbeat's occurrence begins. Start Heartbeats are entirely optional however we recommend using them if you'd like insights into job execution times.

Start Heartbeats requires 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 heartbeat will be treated as a Finish Heartbeat.

Finish Heartbeat

Finish Heartbeats inform AppSignal that the heartbeat's occurrence ends. Unlike Start Heartbeats you do not have to provide AppSignal with a kind attribute. AppSignal treats all heartbeats that do not have a kind attribute of start as Finish heartbeats.

1. Create a heartbeat in AppSignal

Follow our Heartbeat creation instructions to create a new heartbeat. Ensure the heartbeats crontab schedule matches the job you are monitoring.

Note the heartbeat name, 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 is different from your organization-level key and can be found in your app's Push & deploy settings. You can also add your app's name and environment to API requests.

Authenticate with API key

Use your app's AppSignal API key:

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

Authenticate with API key, app name and environment

Use your organization's API key, name and environment.

Note: Replace any spaces in your app's name with %20, for example My%20amazing%20app:

https://appsignal-endpoint.net/heartbeat?api_key=your-app-level-api-key&name=your-app-name-here&environment=your-apps-env-here
 

3. Send heartbeats using URL parameters

To send heartbeats using URL params, you must post heartbeat data to the following URL:

https://appsignal-endpoint.net/heartbeats
 

URL params

1. Send Start Heartbeat

Starting a heartbeat is optional, for a minimal integration you only need to send Finish Heartbeats, however, if you wish to measure your job duration Start Heartbeats are required.

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

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

https://appsignal-endpoint.net/heartbeat?api_key=your-app-level-api-key&heartbeat=your-heartbeat=name&kind=Start
 

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

https://appsignal-endpoint.net/heartbeat?api_key=your-app-level-api-key&heartbeat=your-heartbeat=name&timetamp=your-heartbeat-utc-timestamp&kind=Start&id=your-heartbeat-id
 

Example cURL request

curl -X \
POST 'https://appsignal-endpoint.net/heartbeat?api_key=your-app-level-api-key&heartbeat=your-heartbeat=name&timetamp=your-heartbeat-utc-timestamp&kind=Start&id=your-heartbeat-id'

2. Send Finish Heartbeat

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 heartbeat using only the required params:

https://appsignal-endpoint.net/heartbeat?api_key=your-app-level-api-key&heartbeat=your-heartbeat=name

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

https://appsignal-endpoint.net/heartbeat?api_key=your-app-level-api-key&heartbeat=your-heartbeat=name&timetamp=your-heartbeat-utc-timestamp&kind=finish&id=your-heartbeat-id

Example cURL request

curl -X \
POST 'https://appsignal-endpoint.net/heartbeat?api_key=your-app-level-api-key&heartbeat=your-heartbeat=name&timetamp=your-heartbeat-utc-timestamp&kind=finish&id=your-heartbeat-id'

3. Send heartbeats using NDJSON

To send heartbeats using NDJSON, you must post heartbeat data to the following URL:

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

Remember to authenticate your request.

NDJSON variables

Below are the optional and required NDJSON variables for creating a heartbeat.

1. Send Start Heartbeat

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

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

{"name": "your-heartbeat-name", "kind": "start"}

Below is an example including all additional optional data:

{"name": "your-heartbeat-name", "kind": "start", "timestamp": utc-timestamp, "id": "your-heartbeats-id"}

Example cURL request

curl -X \
POST -H \
 "Content-type: application/json" -d '{"name": "your-heartbeat-name","kind": "start","timestamp": utc-timestamp, "id": "your-heartbeats-id"}' 'https://appsignal-endpoint.net/heartbeats/json'

2. Send Finish Heartbeat

You can send a finish heartbeat by omitting the kind variable or defining it as finish.

Below is an example of a Finish Heartbeat using the minimal data required:

{"name": "your-heartbeat-name"}

Below is an example including all additional optional data:

{"name": "your-heartbeat-name", "kind": "finish", "timestamp": utc-timestamp, "id": "your-heartbeats-id"}

Example cURL request

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

Sending multiple heartbeats in one payload

You can send multiple heartbeats in a single payload with NDJSON.

Our HTTP-JSON endpoint expects heartbeats 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 heartbeats could look:

{"name": "example-heartbeat", "kind": "start", "timestamp": utc-start-timestamp, "id": "EHB123"}
{"name": "example-heartbeat", "kind": "finish", "timestamp": utc-end-timestamp, "id": "EHB123"}

Example cURL request

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

4. Reviewing Heartbeat occurrences in AppSignal

Once configured AppSignal will begin to display occurrence information for your heartbeats.

You can read more about occurrences in our Heartbeat Occurrences documentation.