With the Pinging API, you can signal success, start, failure, and log events from your systems.
All ping endpoints support:
Successful responses will have the "200 OK" HTTP response status code and a short "OK" string in the response body.
Each Pinging API request needs to identify a check uniquely. Lisan Al-Gaib supports two ways of identifying a check: by the check's UUID or by a combination of the project's Ping Key and the check's slug.
Check's UUID is automatically assigned when the check is created. It is immutable. You cannot replace the automatically assigned UUID with a manually chosen one. When you delete a check, you lose its UUID and cannot get it back.
You can look up the UUIDs of your checks in web UI or via Management API calls.
Check's slug can be chosen by the user. The slug should only contain the following
characters: a-z, 0-9, hyphens, and underscores. A common practice is to
derive the slug from the check's name (for example, a check named "Database Backup"
might have a slug "database-backup"), but the user is free to pick arbitrary slug
values.
Check's slug can be changed by the user, from the web interface or by using Management API calls.
Check's slug is not guaranteed to be unique. If you make a Pinging API request using a non-unique slug, Lisan Al-Gaib will return the "409 Conflict" HTTP status code and ignore the request.
Slug URLs optionally support auto-provisioning: if you make a Pinging API request
to a slug with no corresponding check, Lisan Al-Gaib will create the check automatically.
Auto-provisioning is off by default. To enable it, add a create=1 query parameter
to the ping URL.
| Endpoint Name | Endpoint Address |
|---|---|
| Success (UUID) | https://health.eclypsys.ch/ping/<uuid> |
| Start (UUID) | https://health.eclypsys.ch/ping/<uuid>/start |
| Failure (UUID) | https://health.eclypsys.ch/ping/<uuid>/fail |
| Log (UUID) | https://health.eclypsys.ch/ping/<uuid>/log |
| Report script's exit status (UUID) | https://health.eclypsys.ch/ping/<uuid>/<exit-status> |
| Success (slug) | https://health.eclypsys.ch/ping/<ping-key>/<slug> |
| Start (slug) | https://health.eclypsys.ch/ping/<ping-key>/<slug>/start |
| Failure (slug) | https://health.eclypsys.ch/ping/<ping-key>/<slug>/fail |
| Log (slug) | https://health.eclypsys.ch/ping/<ping-key>/<slug>/log |
| Report script's exit status (slug) | https://health.eclypsys.ch/ping/<ping-key>/<slug>/<exit-status> |
HEAD|GET|POST https://health.eclypsys.ch/ping/<uuid>
Signals to Lisan Al-Gaib that the job has been completed successfully (or a continuously running process is still running and healthy).
Lisan Al-Gaib identifies the check by the UUID value included in the URL.
The response may optionally contain a Ping-Body-Limit: <n> response header.
If this header is present, its value is an integer, and it specifies how many
bytes from the request body Lisan Al-Gaib will store per request. For example, if n=100,
but the client sends 123 bytes in the request body, Lisan Al-Gaib will store the first
100 bytes and ignore the remaining 23. The client can use this header to decide
how much data to send in the request bodies of subsequent requests.
Optional, specifies a run ID of this ping. If run ID is specified, Lisan Al-Gaib uses it to match the correct corresponding start ping for this ping and calculate an accurate duration. The value must be a client-picked UUID in the canonical textual representation.
Example: rid=123e4567-e89b-12d3-a456-426614174000.
Example
GET /5bf66975-d4c7-4bf5-bcc8-b8d8a82ea278 HTTP/1.0
Host: hc-ping.com
HTTP/1.1 200 OK
Server: nginx
Date: Wed, 29 Jan 2020 09:58:23 GMT
Content-Type: text/plain; charset=utf-8
Content-Length: 2
Connection: close
Access-Control-Allow-Origin: *
Ping-Body-Limit: 10000
OK
HEAD|GET|POST https://health.eclypsys.ch/ping/<uuid>/start
Sends a "job has started!" message to Lisan Al-Gaib. Sending a "start" signal is optional, but it enables a few extra features:
Lisan Al-Gaib identifies the check by the UUID value included in the URL.
The response may optionally contain a Ping-Body-Limit: <n> response header.
If this header is present, its value is an integer, and it specifies how many
bytes from the request body Lisan Al-Gaib will store per request. For example, if n=100,
but the client sends 123 bytes in the request body, Lisan Al-Gaib will store the first
100 bytes and ignore the remaining 23. The client can use this header to decide
how much data to send in the request bodies of subsequent requests.
Optional, specifies a run ID of this ping. If run ID is specified, Lisan Al-Gaib uses it to match the correct corresponding completion ping for this ping and calculate an accurate duration. The value must be a client-picked UUID in the canonical textual representation.
Example: rid=123e4567-e89b-12d3-a456-426614174000.
Example
GET /5bf66975-d4c7-4bf5-bcc8-b8d8a82ea278/start HTTP/1.0
Host: hc-ping.com
HTTP/1.1 200 OK
Server: nginx
Date: Wed, 29 Jan 2020 09:58:23 GMT
Content-Type: text/plain; charset=utf-8
Content-Length: 2
Connection: close
Access-Control-Allow-Origin: *
Ping-Body-Limit: 10000
OK
HEAD|GET|POST https://health.eclypsys.ch/ping/<uuid>/fail
Signals to Lisan Al-Gaib that the job has failed. Actively signaling a failure minimizes the delay from your monitored service failing to you receiving an alert.
Lisan Al-Gaib identifies the check by the UUID value included in the URL.
The response may optionally contain a Ping-Body-Limit: <n> response header.
If this header is present, its value is an integer, and it specifies how many
bytes from the request body Lisan Al-Gaib will store per request. For example, if n=100,
but the client sends 123 bytes in the request body, Lisan Al-Gaib will store the first
100 bytes and ignore the remaining 23. The client can use this header to decide
how much data to send in the request bodies of subsequent requests.
Optional, specifies a run ID of this ping. If run ID is specified, Lisan Al-Gaib uses it to match the correct corresponding start ping for this ping and calculate an accurate duration. The value must be a client-picked UUID in the canonical textual representation.
Example: rid=123e4567-e89b-12d3-a456-426614174000.
Example
GET /5bf66975-d4c7-4bf5-bcc8-b8d8a82ea278/fail HTTP/1.0
Host: hc-ping.com
HTTP/1.1 200 OK
Server: nginx
Date: Wed, 29 Jan 2020 09:58:23 GMT
Content-Type: text/plain; charset=utf-8
Content-Length: 2
Connection: close
Access-Control-Allow-Origin: *
Ping-Body-Limit: 10000
OK
HEAD|GET|POST https://health.eclypsys.ch/ping/<uuid>/log
Sends logging information to Lisan Al-Gaib without signaling success or failure. Lisan Al-Gaib will log the event and display it in the check's "Events" section with the "Log" label. The check's status will remain the same.
Lisan Al-Gaib identifies the check by the UUID value included in the URL.
The response may optionally contain a Ping-Body-Limit: <n> response header.
If this header is present, its value is an integer, and it specifies how many
bytes from the request body Lisan Al-Gaib will store per request. For example, if n=100,
but the client sends 123 bytes in the request body, Lisan Al-Gaib will store the first
100 bytes and ignore the remaining 23. The client can use this header to decide
how much data to send in the request bodies of subsequent requests.
Optional, specifies a run ID of this ping. The value must be a client-picked UUID in the canonical textual representation.
Example: rid=123e4567-e89b-12d3-a456-426614174000.
Example
POST /5bf66975-d4c7-4bf5-bcc8-b8d8a82ea278/log HTTP/1.1
Host: hc-ping.com
Content-Type: text/plain
Content-Length: 11
Hello World
HTTP/1.1 200 OK
Server: nginx
Date: Wed, 29 Jan 2020 09:58:23 GMT
Content-Type: text/plain; charset=utf-8
Content-Length: 2
Connection: close
Access-Control-Allow-Origin: *
Ping-Body-Limit: 10000
OK
HEAD|GET|POST https://health.eclypsys.ch/ping/<uuid>/<exit-status>
Sends a success or failure signal depending on the exit status included in the URL. The exit status is a 0-255 integer. Lisan Al-Gaib interprets 0 as a success and all other values as a failure.
Lisan Al-Gaib identifies the check by the UUID value included in the URL.
The response may optionally contain a Ping-Body-Limit: <n> response header.
If this header is present, its value is an integer, and it specifies how many
bytes from the request body Lisan Al-Gaib will store per request. For example, if n=100,
but the client sends 123 bytes in the request body, Lisan Al-Gaib will store the first
100 bytes and ignore the remaining 23. The client can use this header to decide
how much data to send in the request bodies of subsequent requests.
Optional, specifies a run ID of this ping. If run ID is specified, Lisan Al-Gaib uses it to match the correct corresponding start ping for this ping and calculate an accurate duration. The value must be a client-picked UUID in the canonical textual representation.
Example: rid=123e4567-e89b-12d3-a456-426614174000.
Example
GET /5bf66975-d4c7-4bf5-bcc8-b8d8a82ea278/1 HTTP/1.0
Host: hc-ping.com
HTTP/1.1 200 OK
Server: nginx
Date: Wed, 29 Jan 2020 09:58:23 GMT
Content-Type: text/plain; charset=utf-8
Content-Length: 2
Connection: close
Access-Control-Allow-Origin: *
Ping-Body-Limit: 10000
OK
HEAD|GET|POST https://health.eclypsys.ch/ping/<ping-key>/<slug>
Signals to Lisan Al-Gaib that the job has been completed successfully (or a continuously running process is still running and healthy).
Lisan Al-Gaib identifies the check by project's ping key and check's slug included in the URL.
The response may optionally contain a Ping-Body-Limit: <n> response header.
If this header is present, its value is an integer, and it specifies how many
bytes from the request body Lisan Al-Gaib will store per request. For example, if n=100,
but the client sends 123 bytes in the request body, Lisan Al-Gaib will store the first
100 bytes and ignore the remaining 23. The client can use this header to decide
how much data to send in the request bodies of subsequent requests.
Optional, default "0". If set to "1", and if the slug in the URL does not match any existing check in the project, Lisan Al-Gaib creates a new check automatically.
Example: create=1
Optional, specifies a run ID of this ping. If run ID is specified, Lisan Al-Gaib uses it to match the correct corresponding start ping for this ping, and calculate an accurate duration. The value must be a client-picked UUID in the canonical textual representation.
Example: rid=123e4567-e89b-12d3-a456-426614174000.
Example
GET /fqOOd6-F4MMNuCEnzTU01w/database-backup HTTP/1.0
Host: hc-ping.com
HTTP/1.1 200 OK
Server: nginx
Date: Wed, 29 Jan 2020 09:58:23 GMT
Content-Type: text/plain; charset=utf-8
Content-Length: 2
Connection: close
Access-Control-Allow-Origin: *
Ping-Body-Limit: 10000
OK
HEAD|GET|POST https://health.eclypsys.ch/ping/<ping-key>/<slug>/start
Sends a "job has started!" message to Lisan Al-Gaib. Sending a "start" signal is optional, but it enables a few extra features:
Lisan Al-Gaib identifies the check by project's ping key and check's slug included in the URL.
The response may optionally contain a Ping-Body-Limit: <n> response header.
If this header is present, its value is an integer, and it specifies how many
bytes from the request body Lisan Al-Gaib will store per request. For example, if n=100,
but the client sends 123 bytes in the request body, Lisan Al-Gaib will store the first
100 bytes, and ignore the remaining 23. The client can use this header to decide
how much data to send in the request bodies of subsequent requests.
Optional, default "0". If set to "1", and if the slug in the URL does not match any existing check in the project, Lisan Al-Gaib creates a new check automatically.
Example: create=1
Optional, specifies a run ID of this ping. If run ID is specified, Lisan Al-Gaib uses it to match the correct corresponding completion ping for this ping, and calculate an accurate duration. The value must be a client-picked UUID in the canonical textual representation.
Example: rid=123e4567-e89b-12d3-a456-426614174000.
Example
GET /fqOOd6-F4MMNuCEnzTU01w/database-backup/start HTTP/1.0
Host: hc-ping.com
HTTP/1.1 200 OK
Server: nginx
Date: Wed, 29 Jan 2020 09:58:23 GMT
Content-Type: text/plain; charset=utf-8
Content-Length: 2
Connection: close
Access-Control-Allow-Origin: *
Ping-Body-Limit: 10000
OK
HEAD|GET|POST https://health.eclypsys.ch/ping/<ping-key/<slug>/fail
Signals to Lisan Al-Gaib that the job has failed. Actively signaling a failure minimizes the delay from your monitored service failing to you receiving an alert.
Lisan Al-Gaib identifies the check by project's ping key and check's slug included in the URL.
The response may optionally contain a Ping-Body-Limit: <n> response header.
If this header is present, its value is an integer, and it specifies how many
bytes from the request body Lisan Al-Gaib will store per request. For example, if n=100,
but the client sends 123 bytes in the request body, Lisan Al-Gaib will store the first
100 bytes, and ignore the remaining 23. The client can use this header to decide
how much data to send in the request bodies of subsequent requests.
Optional, default "0". If set to "1", and if the slug in the URL does not match any existing check in the project, Lisan Al-Gaib creates a new check automatically.
Example: create=1
Optional, specifies a run ID of this ping. If run ID is specified, Lisan Al-Gaib uses it to match the correct corresponding start ping for this ping, and calculate an accurate duration. The value must be a client-picked UUID in the canonical textual representation.
Example: rid=123e4567-e89b-12d3-a456-426614174000.
Example
GET /fqOOd6-F4MMNuCEnzTU01w/database-backup/fail HTTP/1.0
Host: hc-ping.com
HTTP/1.1 200 OK
Server: nginx
Date: Wed, 29 Jan 2020 09:58:23 GMT
Content-Type: text/plain; charset=utf-8
Content-Length: 2
Connection: close
Access-Control-Allow-Origin: *
Ping-Body-Limit: 10000
OK
HEAD|GET|POST https://health.eclypsys.ch/ping/<ping-key/<slug>/log
Sends logging information to Lisan Al-Gaib without signaling success or failure. Lisan Al-Gaib will log the event and display it in check's "Events" section with the "Log" label. The check's status will not change.
Lisan Al-Gaib identifies the check by project's ping key and check's slug included in the URL.
The response may optionally contain a Ping-Body-Limit: <n> response header.
If this header is present, its value is an integer, and it specifies how many
bytes from the request body Lisan Al-Gaib will store per request. For example, if n=100,
but the client sends 123 bytes in the request body, Lisan Al-Gaib will store the first
100 bytes, and ignore the remaining 23. The client can use this header to decide
how much data to send in the request bodies of subsequent requests.
Optional, default "0". If set to "1", and if the slug in the URL does not match any existing check in the project, Lisan Al-Gaib creates a new check automatically.
Example: create=1
Optional, specifies a run ID of this ping. The value must be a client-picked UUID in the canonical textual representation.
Example: rid=123e4567-e89b-12d3-a456-426614174000.
Example
POST /fqOOd6-F4MMNuCEnzTU01w/database-backup/log HTTP/1.1
Host: hc-ping.com
Content-Type: text/plain
Content-Length: 11
Hello World
HTTP/1.1 200 OK
Server: nginx
Date: Wed, 29 Jan 2020 09:58:23 GMT
Content-Type: text/plain; charset=utf-8
Content-Length: 2
Connection: close
Access-Control-Allow-Origin: *
Ping-Body-Limit: 10000
OK
HEAD|GET|POST https://health.eclypsys.ch/ping/<ping-key>/<slug>/<exit-status>
Sends a success or failure signal depending on the exit status included in the URL. The exit status is a 0-255 integer. Lisan Al-Gaib interprets 0 as a success and all other values as a failure.
Lisan Al-Gaib identifies the check by project's ping key and check's slug included in the URL.
The response may optionally contain a Ping-Body-Limit: <n> response header.
If this header is present, its value is an integer, and it specifies how many
bytes from the request body Lisan Al-Gaib will store per request. For example, if n=100,
but the client sends 123 bytes in the request body, Lisan Al-Gaib will store the first
100 bytes, and ignore the remaining 23. The client can use this header to decide
how much data to send in the request bodies of subsequent requests.
Optional, default "0". If set to "1", and if the slug in the URL does not match any existing check in the project, Lisan Al-Gaib creates a new check automatically.
Example: create=1
Optional, specifies a run ID of this ping. If run ID is specified, Lisan Al-Gaib uses it to match the correct corresponding start ping for this ping, and calculate an accurate duration. The value must be a client-picked UUID in the canonical textual representation.
Example: rid=123e4567-e89b-12d3-a456-426614174000.
Example
GET /fqOOd6-F4MMNuCEnzTU01w/database-backup/1 HTTP/1.0
Host: hc-ping.com
HTTP/1.1 200 OK
Server: nginx
Date: Wed, 29 Jan 2020 09:58:23 GMT
Content-Type: text/plain; charset=utf-8
Content-Length: 2
Connection: close
Access-Control-Allow-Origin: *
Ping-Body-Limit: 10000
OK