Webhooks

Webhooks allow you to receive real-time notifications about events in your Ping account, such as message delivery status updates, without polling the API.

Status: Webhook support is currently in development. This documentation describes the planned webhook implementation. Check back soon for availability.

Webhook events

When webhook support launches, you'll be able to subscribe to the following event types:

SMS events

Name
sms.sent
Description
SMS was accepted by the provider.
Name
sms.delivered
Description
SMS was successfully delivered to the recipient.
Name
sms.failed
Description
SMS delivery failed.

WhatsApp events

Name
whatsapp.sent
Description
WhatsApp message was sent to Meta's servers.
Name
whatsapp.delivered
Description
Message was delivered to the recipient's device.
Name
whatsapp.read
Description
Recipient read the message (blue ticks).
Name
whatsapp.failed
Description
Message delivery failed.

Email events

Name
email.sent
Description
Email was accepted by the email provider.
Name
email.delivered
Description
Email was delivered to recipient's mailbox.
Name
email.bounced
Description
Email bounced (invalid address or mailbox full).
Name
email.opened
Description
Recipient opened the email (tracked).
Name
email.clicked
Description
Recipient clicked a link in the email.
Name
email.failed
Description
Email delivery failed.

Why use webhooks?

Real-time delivery updates
No need to poll the API
Lower latency than polling
More efficient for high-volume operations
Automatic retry on failure

Webhook payload

All webhook events will be sent as HTTP POST requests to your configured endpoint URL with a JSON payload.

Common fields

Every webhook payload will include:

event - Event type (e.g., "sms.delivered")
timestamp - When the event occurred (ISO 8601)
notification_id - Unique ID of the notification
data - Event-specific data

Example payloads

SMS delivery event:

{
  "event": "sms.delivered",
  "timestamp": "2025-01-15T10:30:00Z",
  "notification_id": "sms_abc123def456",
  "data": {
    "to_phone": "+263771234567",
    "message_id": "SM1234567890abcdef",
    "status": "delivered",
    "provider": "econet"
  }
}

Email opened event:

{
  "event": "email.opened",
  "timestamp": "2025-01-15T10:35:22Z",
  "notification_id": "email_abc123def456",
  "data": {
    "to_email": "[email protected]",
    "subject": "Welcome to Ping",
    "opened_at": "2025-01-15T10:35:22Z",
    "user_agent": "Mozilla/5.0..."
  }
}

Webhook endpoint requirements

Your webhook endpoint must:

Accept HTTP POST requests
Return 200-299 status code for success
Respond within 10 seconds
Use HTTPS (required for production)

Example endpoint (Python/Flask):

from flask import Flask, request

app = Flask(__name__)

@app.route('/webhooks/ping', methods=['POST'])
def ping_webhook():
    payload = request.json
    event = payload['event']

    if event == 'sms.delivered':
        # Update your database
        update_delivery_status(
            payload['notification_id'],
            'delivered'
        )

    return '', 200

Signature verification

Webhook requests will be signed so you can verify they came from Ping and not a malicious source.

Verification process

Ping will send a signature in the X-Ping-Signature header
The signature is an HMAC-SHA256 hash of the request body
Use your webhook secret (from dashboard) to verify the signature

Example verification

import hmac
import hashlib

def verify_webhook_signature(payload_body, signature, secret):
    """Verify the webhook signature."""
    expected_signature = hmac.new(
        secret.encode(),
        payload_body.encode(),
        hashlib.sha256
    ).hexdigest()

    return hmac.compare_digest(signature, expected_signature)

# In your webhook handler:
signature = request.headers.get('X-Ping-Signature')
secret = 'your_webhook_secret_from_dashboard'

if not verify_webhook_signature(request.data, signature, secret):
    return 'Invalid signature', 401

Retry logic

If your endpoint returns a non-2xx status code or times out:

Ping will retry up to 3 times
Retry delays: 1 minute, 10 minutes, 1 hour
After 3 failures, the webhook event is discarded

Security best practices:

Always verify the signature
Use HTTPS for your webhook endpoint
Rotate webhook secrets periodically
Rate limit webhook endpoints
Log failed signature verifications
Store webhook secrets securely (environment variables)

Configuration (Coming Soon)

When webhook support is available, you'll be able to:

Register webhook endpoints in your Ping dashboard
Select events to subscribe to (or subscribe to all events)
Configure retry behavior and failure notifications
Test webhooks with sample payloads before going live
Monitor webhook delivery with logs and statistics
Manage webhook secrets for signature verification

Stay tuned for updates on webhook availability.