Troubleshooting

Common issues and their solutions.

Not Receiving Notifications

1. Check Notification Permissions

On your iPhone:

1. Open Settings
2. Scroll to Ping
3. Tap Notifications
4. Ensure Allow Notifications is enabled

2. Verify Your Webhook URL

Test with curl and check the response:

curl -X POST 'YOUR_WEBHOOK_URL' \
  -H 'Content-Type: application/json' \
  -d '{"title": "Test"}'

You should see: {"ok": true, "id": "msg_..."}

3. Check Your Internet Connection

Both your sending system and iPhone need internet access.

4. Ensure You're Signed In

Open the app and verify you're signed in. If you see the sign-in screen, authenticate again.

5. Device-Specific Issues

• Low Power Mode may delay notifications
• Focus modes may filter notifications
• Do Not Disturb silences notifications

Webhook Errors

invalid_json

Your request body isn't valid JSON.

Common causes:

• Missing quotes around strings
• Trailing commas
• Special characters not escaped

Solution: Use a JSON validator or the printf method:

printf '{"title":"Hello"}' | curl -s -X POST 'YOUR_URL' -H 'Content-Type: application/json' -d @-

invalid_payload

Missing required fields or exceeded limits.

Check:

• title is present and under 100 characters
• body (if present) is under 10,000 characters
• priority is one of: low, normal, high
• callback_url is provided when using interactive actions

invalid_token

The channel doesn't exist or the URL is wrong.

Check:

• The webhook URL is correct
• The channel hasn't been deleted
• You haven't regenerated the token

rate_limited

Too many requests to this channel.

Solution: Wait a moment and retry, or create multiple channels for high-volume use cases.

Authentication Issues

Can't Sign In

1. Ensure you have a stable internet connection
2. Check that Sign in with Apple works in other apps
3. Try signing out of iCloud and back in

Session Expired

Sessions last 30 days. If you get authentication errors:

1. Sign out
2. Sign back in

Best Practices

Channel Organization

Create separate channels for different sources:

Priority Usage

Tip: Reserve high priority for truly urgent matters. Overuse reduces its effectiveness.

Security

Keep your webhook URLs private:

• Don't commit them to public repositories
• Use environment variables or secrets managers
• Regenerate tokens if exposed

Example with environment variables:

# Set in your environment
export PING_URL="https://ping-api-production.up.railway.app/v1/send/YOUR_TOKEN"

# Use in scripts
curl -X POST "$PING_URL" -H 'Content-Type: application/json' -d '{"title": "Alert"}'

Error Handling

Always check webhook responses in production:

const response = await fetch(WEBHOOK_URL, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ title: 'Alert' })
});

if (!response.ok) {
  const error = await response.json();
  console.error('Failed to send notification:', error);
  // Handle error (retry, fallback, etc.)
}

FAQ

Is Ping free?

Ping offers a free tier and a Pro plan:

How many channels can I create?

• Free plan: Up to 3 channels
• Pro plan: Unlimited channels

What's the message retention period?

• Free plan: 7 days
• Pro plan: 90 days

Can I use Ping for marketing notifications?

Ping is designed for developer notifications from automated systems. It's not intended for marketing or user-facing notifications.

Does Ping work on iPad?

Ping is currently iPhone-only. iPad support may come in a future update.

Can I use Ping on Android?

Ping is iOS-only as it relies on Apple Push Notifications. There are no current plans for Android support.

How fast are notifications delivered?

Typically within 1-2 seconds. Actual delivery time depends on network conditions and Apple's push notification service.

Can I send notifications to multiple devices?

Yes! Sign in with the same Apple ID on multiple devices, and all will receive notifications.

What happens if I delete a channel?

All messages in that channel are permanently deleted. The webhook URL stops working immediately.

Can I recover a deleted channel?

No. Channel deletion is permanent. You'll need to create a new channel and update your integrations.

Support

• GitHub Issues: github.com/actanonverbos/ping-api/issues
• Web Dashboard: getping.pro