Slug URLs

Overview

Slug URLs provide an alternative, human-readable format for ping URLs. Instead of using a random token in each URL, you use a single ping key (per organization) combined with a slug (per heartbeat).

Why slug URLs?

• Readable: URLs like ping.cronping.com/abc123/db-backup are self-documenting
• Safe to commit: The slug (db-backup) isn't a secret — only the ping key is
• One secret for all heartbeats: Rotate the ping key once to invalidate all slug URLs at once
• Mutable: Change the slug without regenerating tokens

Setup

1. Generate a ping key

Go to Organization Settings → General → Ping Key and click Generate Ping Key. This creates a 24-character secret key shared by all heartbeats in the organization.

2. Set slugs on your heartbeats

When creating or editing a heartbeat, fill in the Slug field. Slugs must be:

• Lowercase alphanumeric with hyphens (a-z, 0-9, -)
• No leading or trailing hyphens
• Unique within the organization
• 1–100 characters

If you leave the slug empty when creating a heartbeat, one is auto-generated from the name (e.g., "Daily DB Backup" → daily-db-backup).

3. Use the slug URL

curl -fsS -m 10 https://ping.cronping.com/<ping-key>/<slug>

Endpoints

Slug URLs support all the same actions as token URLs:

The optional ?rid=<uuid> query parameter works with slug URLs too.

Examples

Basic crontab

# Token URL (traditional)
*/5 * * * * curl -fsS -m 10 https://ping.cronping.com/Abc123xyz...

# Slug URL (human-readable)
*/5 * * * * curl -fsS -m 10 https://ping.cronping.com/myPingKey123/db-backup

Script with start and exit code

#!/bin/sh
PING_KEY="your-ping-key"
SLUG="db-backup"
BASE="https://ping.cronping.com/${PING_KEY}/${SLUG}"

curl -fsS -m 10 "${BASE}/start"
/usr/bin/backup.sh
curl -fsS -m 10 "${BASE}/$?"

Multiple jobs sharing one ping key

PING_KEY="your-ping-key"

# Each job uses a different slug — all share the same key
curl -fsS https://ping.cronping.com/${PING_KEY}/db-backup
curl -fsS https://ping.cronping.com/${PING_KEY}/cache-warm
curl -fsS https://ping.cronping.com/${PING_KEY}/invoice-generation

Token URLs vs Slug URLs

Both formats are fully supported and can be used simultaneously for the same heartbeat.

Regenerating the ping key

You can regenerate the ping key from Organization Settings → General → Ping Key. This will:

• Immediately invalidate all slug-based ping URLs for the organization
• Not affect token-based ping URLs
• Generate a new 24-character key

Auto-provisioning

With slug URLs you can auto-create heartbeats on first ping by adding ?create=1 to the URL. If the slug doesn't exist yet in the organization, Cronping creates a new heartbeat for it automatically and processes the incoming ping — no dashboard setup required.

curl -fsS https://ping.cronping.com/<ping-key>/new-job?create=1

How it works

1. You send a ping to a slug that doesn't exist yet, with ?create=1.
2. Cronping looks up the organization by the ping key.
3. A new heartbeat is created with the slug as its name.
4. The ping is processed normally (success, start, fail, etc.).
5. The response returns HTTP 201 with "created": true in the body.

Subsequent pings to the same slug (with or without ?create=1) hit the existing heartbeat and return the normal 200 response.

Default settings

Auto-provisioned heartbeats are created with sensible defaults:

You can adjust these from the dashboard after the heartbeat is created.

Limits

Auto-provisioning is subject to an organization-wide hard cap of 200 heartbeats. If the cap is reached, the ping returns 404 instead of creating a new heartbeat.

Use cases

Auto-provisioning is especially useful for:

• Dynamic infrastructure: Kubernetes pods, serverless functions, or auto-scaled workers that register themselves on first run.
• CI/CD pipelines: Jobs that create their own heartbeat without a separate setup step.
• Scripted deployments: A deploy script can reference future heartbeat slugs and create them on demand.

Example: self-registering worker

#!/bin/sh
PING_KEY="your-ping-key"
# Use hostname as slug — heartbeat is auto-created on first ping
SLUG="worker-$(hostname)"

curl -fsS "https://ping.cronping.com/${PING_KEY}/${SLUG}/start?create=1"
do_work
curl -fsS "https://ping.cronping.com/${PING_KEY}/${SLUG}/$?"

Switching URL format

The heartbeat detail page includes a UUID / Slug toggle on the Ping URL card. Use it to switch between displaying the token-based URL and the slug-based URL. Both formats work at the same time — switching the display doesn't disable either format.