HulkPush

HulkPush API

REST API to send push notifications, manage subscribers, and view analytics programmatically.

Get API Key

Authentication

All API requests require an API key sent in the X-HulkPush-Key header.

curl -X POST https://hulkpush.com/api/v1/push/send \
  -H "X-HulkPush-Key: hp_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"site_id": 1, "title": "Hello!", "body": "Test notification", "url": "https://example.com"}'
Rate Limiting: Each API key has a configurable rate limit (default: 60 requests/minute). Exceeding the limit returns a 429 status code.

Push Notifications

POST /api/v1/push/send

Send an instant push notification to all subscribers (or a segment) of a site.

Parameters

Name Type Required Description
site_idintegerYesYour site ID
titlestringYesNotification title (max 65 chars)
bodystringYesNotification body (max 120 chars)
urlstringYesClick-through URL
icon_urlstringNoNotification icon URL
image_urlstringNoLarge image URL
segment_idintegerNoTarget a specific segment
ttlintegerNoTime to live in seconds (60-86400, default: 3600)
actionsarrayNoUp to 2 action buttons [{title, url}]

Response

{
  "success": true,
  "campaign_id": 42,
  "message": "Push notification is being sent."
}
POST /api/v1/push/schedule

Schedule a push notification for a future date/time.

Same parameters as /push/send plus scheduled_at (required, ISO 8601 datetime in the future).

Subscribers

GET /api/v1/subscribers

List subscribers with pagination. Filter by site_id, status, country, device_type, browser.

Permission: subscribers:read

GET /api/v1/subscribers/count

Get total, active, and unsubscribed count. Optional: site_id, status filters.

DELETE /api/v1/subscribers/{id}

Unsubscribe a specific subscriber by ID.

Permission: subscribers:write

Campaigns

GET /api/v1/campaigns

List campaigns with pagination. Filter by site_id, status, type.

GET /api/v1/campaigns/{id}

Get campaign details with notification info and delivery stats (sent, delivered, clicked, CTR).

Analytics

GET /api/v1/analytics/overview

Get analytics overview: total/active subscribers, sent, clicked, CTR, delivery rate. Optional: days param (default: 30).

Sites

GET /api/v1/sites

List all your sites with ID, name, domain, status, and subscriber count.

Webhooks

Configure webhooks in your dashboard to receive real-time event notifications via POST requests.

Available Events

  • push.sent - When a push notification is delivered
  • push.clicked - When a subscriber clicks a notification
  • subscriber.new - When a new subscriber registers
  • subscriber.unsubscribed - When a subscriber unsubscribes

Verifying Signatures

$signature = hash_hmac('sha256', $requestBody, $yourSecretKey);
if (hash_equals($signature, $request->header('X-HulkPush-Signature'))) {
    // Valid webhook
}

Error Codes

Code Description
401Invalid or missing API key
403Insufficient permissions
404Resource not found
422Validation error (check response body for details)
429Rate limit exceeded (retry after 60 seconds)

Code Examples

curl -X POST https://hulkpush.com/api/v1/push/send \
  -H "X-HulkPush-Key: hp_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "site_id": 1,
    "title": "New Video!",
    "body": "Check out our latest upload",
    "url": "https://youtube.com/watch?v=xxx",
    "image_url": "https://img.youtube.com/vi/xxx/maxresdefault.jpg"
  }'
$response = Http::withHeaders([
    'X-HulkPush-Key' => 'hp_your_api_key',
])->post('https://hulkpush.com/api/v1/push/send', [
    'site_id' => 1,
    'title'   => 'New Video!',
    'body'    => 'Check out our latest upload',
    'url'     => 'https://youtube.com/watch?v=xxx',
]);

$data = $response->json();
const response = await fetch('https://hulkpush.com/api/v1/push/send', {
  method: 'POST',
  headers: {
    'X-HulkPush-Key': 'hp_your_api_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    site_id: 1,
    title: 'New Video!',
    body: 'Check out our latest upload',
    url: 'https://youtube.com/watch?v=xxx',
  }),
});

const data = await response.json();
import requests

response = requests.post(
    'https://hulkpush.com/api/v1/push/send',
    headers={'X-HulkPush-Key': 'hp_your_api_key'},
    json={
        'site_id': 1,
        'title': 'New Video!',
        'body': 'Check out our latest upload',
        'url': 'https://youtube.com/watch?v=xxx',
    }
)

data = response.json()