Skip to content
Island Pulse

FAQ

Setup

The activity never appears after my first POST. What’s wrong?

The most common causes, in order:

  1. The app hasn’t launched on device. Island Pulse must be opened at least once on your physical iPhone so it can connect to the service. Open the app, wait a few seconds, then try again.
  2. Notifications are not enabled. Go to iOS Settings → Notifications → Island Pulse → allow notifications.
  3. You’re testing on the Simulator. Island Pulse requires a real device. You can verify your JSON gets a 200 response, but the Live Activity won’t appear until you test on hardware.
  4. Wrong webhook URL. Copy the URL fresh from the app home screen and paste it directly into your terminal. Avoid invisible characters from copy-paste.

Can I test without a real iPhone?

Partially. You can confirm your JSON payload is valid and receive a 200 response. But Live Activities themselves only appear on a physical device running iOS 17.2 or later.

Payload & fields

What is job_id?

It is the required field that identifies which Live Activity a POST updates. Use 1–64 characters: letters, digits, underscores, and hyphens only. Older aliases like job_name are not read; put the value in job_id. If job_id is missing, the API returns 400 MISSING_JOB_ID.

Does the title field do anything?

Yes. title is the user-facing title shown on the Live Activity card and Dynamic Island expanded view. job_id is routing only and is never shown as the title.

The start notification banner uses the same resolved title automatically. If title is omitted, Island Pulse derives it from message.

What field names can I use instead of message?

Use message for the main body text shown on the Live Activity.

Can I pass progress as a percentage (0–100)?

Yes. Island Pulse normalizes values greater than 1 by dividing by 100. Passing 75 and 0.75 are equivalent.

Limits & tiers

How many concurrent Live Activities can I run?

Free tier: 1 active job_id per webhook URL at a time. Sending a different job_id while one is active returns 403 FREE_TIER_JOB_LOCKED (support code TIER_LIMIT_EXCEEDED) and includes the currently locked job ID in the response. Pro tier: up to the iOS system limit of 5 simultaneous Live Activities per app.

How long does a Live Activity stay on screen?

iOS limits Live Activities to 8 hours. After that the session expires. Pro users get automatic renewal, the next POST seamlessly starts a fresh session. Free users need to wait for the current activity to be dismissed before starting a new one.

What’s in the run history?

Free tier keeps the last 10 completed runs. Pro keeps 30 days of history. Both are viewable in the Island Pulse app’s History tab.

Webhook URL

Is the webhook URL secret?

Yes. The URL contains your unique ID, which acts as your API key. Treat it like a password, store it in environment variables or CI secrets, never in version control. Anyone with the URL can push updates to your phone.

How should I send the secret when I POST?

Yes. Send Authorization: Bearer <same unique ID> to /notify. The ID is the same value shown in the app.

How do I rotate my webhook URL?

Go to Island Pulse → Settings → tap “Generate new secret URL”. This invalidates the old URL immediately and gives you a new one. Update your integrations with the new URL.

Can I use the same URL from multiple services?

Yes. Multiple tools can POST to the same URL simultaneously. Use distinct job_id values to keep each source in its own Live Activity.

Behavior

Why does the activity not dismiss when my job finishes?

Setting status: "success" or status: "failed" changes the visual state but does not dismiss the card, it stays visible so you can read the result. To dismiss it programmatically, send a final POST with "action": "end". The user can also swipe it away manually.

What happens if my iPhone is offline when an update is sent?

Island Pulse queues the most recent update for a short window. When the device comes back online, the latest state is delivered. Intermediate updates sent while offline are not replayed, only the most recent one is delivered.

Why did I get a 502 APNS_PUSH_FAILED error?

Island Pulse couldn’t deliver the update to your device. The most common reason is an outdated device connection, this happens after a reinstall or iOS upgrade. Open Island Pulse on your device to reconnect, then retry your webhook.

Can I customize the icon and color per push?

Yes. Include icon (any SF Symbol name) and accentColor (hex or CSS color name) in any payload. These can change on every update, for example, green on success and red on failure.