Outbound Webhooks & Event Notifications

📁 Developer API & Security 🕐 Updated 53 minutes ago

Outbound Webhooks & Event Notifications

Receive real-time HTTP POST notification callbacks on your backend server whenever subscriber opt-ins, push deliveries, clicks, or token expirations occur in HyperPush X.

📷 Live System Interface: Outbound Webhooks Registration

Real API Keys & Outbound Webhooks Panel

📐 Webhook Signature & Dispatch Diagram

Webhook Setup Step

🔗 Supported Webhook Event Types

Event Name	Trigger Condition	Payload Includes
`subscriber.opt_in`	A new visitor accepts the permission prompt and subscribes.	Subscriber ID, Browser, OS, Opt-In Timestamp.
`notification.delivered`	Push service confirms successful delivery to device.	Campaign ID, Subscriber ID, Delivered At.
`notification.clicked`	User clicks the push notification banner or action button.	Campaign ID, Subscriber ID, Destination URL, Clicked At.
`token.expired`	Push endpoint is revoked or flagged HTTP `410 Gone`.	Subscriber ID, Reason, Expired At.

📦 Webhook Payload Format

HyperPush X posts raw JSON bodies to your configured endpoint URL:

{
  "event": "notification.clicked",
  "event_id": "evt_9b1deb4d3b7d4bad",
  "timestamp": 1758675600,
  "data": {
    "campaign_id": "cmp_8a1ce32b",
    "subscriber_id": "sub_4f2a991c",
    "url": "https://yoursite.com/deals/flash-sale",
    "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) Chrome/128.0.0.0"
  }
}

🔒 HMAC-SHA256 Signature Verification

To ensure webhook calls originate exclusively from HyperPush X and have not been altered in transit, every HTTP POST request contains the X-HyperPush-Signature header.

PHP Signature Verification Code

<?php
$payload = file_get_contents('php://input');
$receivedSignature = $_SERVER['HTTP_X_HYPERPUSH_SIGNATURE'] ?? '';
$webhookSecret = 'YOUR_WEBHOOK_SECRET_KEY';

$expectedSignature = hash_hmac('sha256', $payload, $webhookSecret);

if (hash_equals($expectedSignature, $receivedSignature)) {
    // Signature is valid! Process event
    http_response_code(200);
    echo json_encode(['status' => 'success']);
} else {
    // Invalid signature! Reject request
    http_response_code(401);
    exit('Invalid webhook signature');
}

Node.js (Express) Signature Verification

const crypto = require('crypto');
const express = require('express');
const app = express();

app.post('/api/webhooks/hyperpush', express.raw({ type: 'application/json' }), (req, res) => {
    const signature = req.headers['x-hyperpush-signature'];
    const webhookSecret = 'YOUR_WEBHOOK_SECRET_KEY';

    const hmac = crypto.createHmac('sha256', webhookSecret);
    const digest = hmac.update(req.body).digest('hex');

    if (crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(digest))) {
        const event = JSON.parse(req.body);
        console.log(`Received event: ${event.event}`);
        res.status(200).send({ received: true });
    } else {
        res.status(401).send('Signature verification failed');
    }
});

🔁 Retry Policy & Delivery Guarantees

Delivery Timeout: HyperPush X expects your webhook receiver to return an HTTP 200 or 204 response within 5 seconds.
Exponential Backoff: If your server returns a non-2xx status code or times out, HyperPush X automatically retries delivery up to 3 times:
- Attempt 1: Immediate retry after 30 seconds
- Attempt 2: 5 minutes later
- Attempt 3: 30 minutes later