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 only field that identifies which Live Activity a POST updates. Use 1–64 characters: letters, digits, underscores, and hyphens only. Omit job_id to use the built-in default key (single-activity setups). Older aliases like job_name are not read; put the value in job_id.

Does the title field do anything?

No, there is no title field in the payload schema. The main text displayed on the activity is message. If you want to customize the notification banner that briefly appears when an activity first starts, use alertTitle (defaults to the job_id string if omitted).

What field names can I use instead of message?

Island Pulse accepts these aliases in priority order: message, body, text, msg, description, detail, alertBody. This lets tools like Zapier or Make send their native field names without transformation.

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 concurrent Live Activity. Starting a second while one is active returns a 403 TIER_LIMIT_EXCEEDED error. 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.

Can I avoid putting the secret in the URL when I POST?

Yes. Send Authorization: Bearer <same unique ID> to /notify (or use ?token=). That way log files that capture URLs are less likely to contain your secret. The ID is still the same value as in the app’s webhook URL.

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.