Sending Webhooks
Send a POST request to your webhook URL to trigger a push notification.
Basic Request
Terminal
curl -X POST 'https://ping-api-production.up.railway.app/v1/send/YOUR_TOKEN' \
-H 'Content-Type: application/json' \
-d '{"title": "Hello World"}'Preview
Hello World
just nowPayload Reference
| Field | Type | Required | Description | Constraints |
|---|---|---|---|---|
title | string | Yes | Notification title | Max 100 characters |
body | string | No | Notification body (supports Markdown) | Max 10,000 characters |
priority | string | No | Delivery priority | low, normal, high |
callback_url | string | Conditional | URL to receive action responses | Required for interactive actions |
actions | array | No | Interactive actions | Max 5 actions |
Full Example
JSON
{
"title": "Build Failed",
"body": "CI pipeline failed on main branch at commit abc123",
"priority": "high",
"actions": [
{"type": "url", "label": "View Build", "value": "https://github.com/org/repo/actions/runs/123"},
{"type": "url", "label": "View Logs", "value": "https://ci.example.com/logs/123"}
]
}Preview
Build Failed
just nowCI pipeline failed on main branch at commit abc123
Priority Levels
| Priority | Behavior |
|---|---|
high | Plays a sound, shows alert indicator |
normal | Standard notification (default) |
low | Lower priority delivery |
Use high priority sparingly for truly urgent alerts. Overusing it reduces its effectiveness.
Markdown Support
The body field supports Markdown formatting, which is rendered beautifully in the iOS app. This is ideal for AI-generated content, reports, and structured messages.
Supported formatting:
- Bold:
**text**or__text__ - Italic:
*text*or_text_ Inline code:`code`- Links:
[label](url)
Example: Traffic Report with Markdown
JSON
{
"title": "š Traffic Update",
"body": "**ā½ EVENTS & SCHEDULED DISRUPTIONS**\n\nš“ **Southampton vs Leicester City** - Tuesday, 18 Nov **in 3 days**\n\nSt. Mary's Stadium\n- Peak congestion: 18:30-20:30 before, 22:00-23:00 after\n- Most affected: *Britannia Road*, *St Mary's Road*"
}Preview
š Traffic Update
just nowā½ EVENTS & SCHEDULED DISRUPTIONS š“ Southampton vs Leicester City - Tuesday, 18 Nov in 3 days St. Mary's Stadium - Peak congestion: 18:30-20:30 before, 22:00-23:00 after - Most affected: Britannia Road, St Mary's Road
Response Format
Success
JSON
{
"ok": true,
"id": "msg_xxxxxxxxxxxx",
"muted": false
}| Field | Description |
|---|---|
ok | Always true on success |
id | Unique message identifier for tracking or polling |
muted | true if the channel is muted (message stored, but no push sent) |
Error
JSON
{
"error": "error_code",
"message": "Human-readable description"
}Error Handling
| Error Code | HTTP Status | Description | Solution |
|---|---|---|---|
invalid_json | 400 | Request body isn't valid JSON | Check JSON syntax |
invalid_payload | 400 | Missing title, exceeds limits, or missing callback_url | Verify required fields |
invalid_token | 401 | Channel not found | Check webhook URL |
rate_limited | 429 | Too many requests | Wait and retry |
Common invalid_payload errors:
- Missing
titlefield callback_urlmissing when using interactive actions- Field exceeds character limits
Rate Limits
| Plan | Webhook Rate | Other Endpoints |
|---|---|---|
| Free | 5/min per channel | 60/min per endpoint |
| Pro | 200/min per channel | 200/min per endpoint |
When rate limited, you'll receive HTTP 429. Wait before retrying (exponential backoff recommended).
Related
- Interactive Actions - Add buttons and forms
- Callbacks & Polling - Receive user responses
- Webhook Signatures - Verify callback authenticity