Webhook Callbacks for Notification Delivery

Real-Time Delivery Events, Pushed to You

When you send a notification through the One-Ping REST API, the initial response tells you the message was accepted and queued. But what happens next? Did the Telegram message actually reach the user? Did the email bounce? Did the Slack webhook return an error?

One-Ping webhooks answer these questions in real time. Instead of polling the API or checking the dashboard manually, you register a callback URL and we push delivery events to your server as they happen. Your application stays in sync with the actual delivery status of every notification you send, across every channel.

This is essential for building reliable notification workflows where you need to know whether a message was delivered -- not just that it was sent. Update your database, notify your team, trigger follow-up actions, or escalate to an alternative channel, all automatically based on webhook events.

How Webhooks Work

The webhook flow is straightforward. When you send a notification, One-Ping processes it and dispatches to the requested channels. As each channel confirms delivery (or reports a failure), One-Ping sends an HTTP POST request to your registered callback URL with the event details.

Webhook Event Types

One-Ping sends different webhook events depending on what happens with your notification. Each event type is identified by the event field in the payload.

Webhook Payload Format

Every webhook event is delivered as an HTTP POST request with a JSON body. Here is the full payload structure with an example for a successful delivery.

Delivery Success Event

// POST to your webhook URL
{
  "event": "notification.delivered",
  "notification_id": "msg_a1b2c3d4e5",
  "channel": "telegram",
  "status": "delivered",
  "recipient": "@username",
  "delivered_at": "2025-01-15T10:30:05Z",
  "latency_ms": 245,
  "attempt": 1,
  "metadata": {
    "order_id": "ORD-5678"
  },
  "timestamp": "2025-01-15T10:30:05Z"
}

Delivery Failure Event

{
  "event": "notification.failed",
  "notification_id": "msg_a1b2c3d4e5",
  "channel": "email",
  "status": "failed",
  "recipient": "[email protected]",
  "error": {
    "code": "RECIPIENT_REJECTED",
    "message": "Mailbox not found"
  },
  "attempts": 3,
  "first_attempt_at": "2025-01-15T10:30:00Z",
  "last_attempt_at": "2025-01-15T10:35:00Z",
  "metadata": {},
  "timestamp": "2025-01-15T10:35:01Z"
}

Retry Event

{
  "event": "notification.retrying",
  "notification_id": "msg_a1b2c3d4e5",
  "channel": "slack",
  "status": "retrying",
  "attempt": 2,
  "max_attempts": 3,
  "next_retry_at": "2025-01-15T10:32:00Z",
  "error": {
    "code": "TIMEOUT",
    "message": "Channel did not respond within 10 seconds"
  },
  "timestamp": "2025-01-15T10:31:00Z"
}

Security: Signature Verification

Every webhook request from One-Ping includes a cryptographic signature so you can verify that the request genuinely came from us and was not tampered with in transit. You should always verify webhook signatures in production to prevent spoofed events from affecting your application.

How Signature Verification Works

One-Ping signs each webhook payload using HMAC-SHA256 with your webhook secret key. The signature is included in the X-OnePing-Signature header. To verify the signature, compute the HMAC-SHA256 hash of the raw request body using your secret and compare it with the header value.

// Webhook headers sent by One-Ping
X-OnePing-Signature: sha256=a1b2c3d4e5f6...
X-OnePing-Timestamp: 1705312200
Content-Type: application/json

Verification Example (Node.js)

const crypto = require('crypto');

function verifyWebhook(req, secret) {
  const signature = req.headers['x-oneping-signature'];
  const timestamp = req.headers['x-oneping-timestamp'];

  // Reject requests older than 5 minutes to prevent replay attacks
  const age = Math.abs(Date.now() / 1000 - parseInt(timestamp));
  if (age > 300) return false;

  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(timestamp + '.' + JSON.stringify(req.body))
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Verification Example (Python)

import hmac
import hashlib
import time
import json

def verify_webhook(headers, body, secret):
    signature = headers.get('X-OnePing-Signature')
    timestamp = headers.get('X-OnePing-Timestamp')

    # Reject requests older than 5 minutes
    if abs(time.time() - int(timestamp)) > 300:
        return False

    payload = f"{timestamp}.{json.dumps(body)}"
    expected = 'sha256=' + hmac.new(
        secret.encode(),
        payload.encode(),
        hashlib.sha256
    ).hexdigest()

    return hmac.compare_digest(signature, expected)

Use Cases for Webhooks

Webhooks unlock powerful automation capabilities on top of your notification workflow. Here are the most common patterns our users build with webhook callbacks.

Webhook Delivery Retry Logic

We understand that your server might not always be available to receive webhooks. If your endpoint does not respond with a 200 status code, One-Ping retries the webhook delivery using exponential backoff.

After 5 failed attempts, the webhook event is marked as failed and logged in your dashboard. You can manually re-trigger any failed webhook from the dashboard if needed.

Best Practices

• Respond quickly: Return a 200 status code as soon as possible. Process the webhook event asynchronously (queue it) rather than doing heavy work in the handler.
• Handle duplicates: In rare cases, a webhook event might be delivered more than once. Use the notification_id and event fields to detect and ignore duplicate events.
• Always verify signatures: Check the X-OnePing-Signature header on every request. Never trust unverified webhook payloads.
• Log everything: Store incoming webhook events for debugging and auditing. If something goes wrong, your logs will help you trace the issue.
• Use HTTPS: Your webhook endpoint should always use HTTPS to encrypt the webhook payload in transit. One-Ping will not deliver webhooks to plain HTTP URLs in production.
• Set up monitoring: Monitor your webhook handler for errors and latency. If your handler starts failing, you will miss delivery events until the retries succeed.