Webhooks

RankFlo webhooks deliver real-time notifications to your server when events occur. Use them to trigger deployments, update caches, and keep external systems in sync.

Event Types

Event	Description
`post.published`	A post is published or goes live after scheduling
`post.updated`	A published post is edited
`post.deleted`	A post is deleted
`media.uploaded`	A file is uploaded

Payload Format

json

{
  "id": "evt_01abc123",
  "type": "post.published",
  "timestamp": "2025-01-15T10:30:00Z",
  "data": {
    "id": "post_01xyz",
    "title": "Hello World",
    "slug": "hello-world",
    "status": "PUBLISHED"
  }
}

Header	Description
`X-RankFlo-Event`	Event type
`X-RankFlo-Delivery`	Unique delivery ID
`X-RankFlo-Signature`	HMAC-SHA256 signature
`X-RankFlo-Timestamp`	Unix timestamp

Signature Verification

The signature is computed over: {timestamp}.{raw_body}

Node.js

javascript

import crypto from "node:crypto";

function verifyWebhookSignature(payload, signature, timestamp, secret) {
  const signedPayload = `${timestamp}.${payload}`;
  const expected = crypto
    .createHmac("sha256", secret)
    .update(signedPayload)
    .digest("hex");

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

Python

python

import hmac, hashlib

def verify_webhook_signature(payload, signature, timestamp, secret):
    signed_payload = f"{timestamp}.{payload.decode()}"
    expected = hmac.new(
        secret.encode(), signed_payload.encode(), hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(signature, expected)

Reject any delivery where the timestamp is more than 5 minutes old to prevent replay attacks.

Retry Policy

Attempt	Delay
1st retry	1 minute
2nd retry	5 minutes
3rd retry	30 minutes
4th retry	2 hours
5th retry	12 hours

Configuring Webhooks

Navigate to Settings → Webhooks
Click Add endpoint
Enter your endpoint URL (must be HTTPS)
Select the events to subscribe to
Copy the generated signing secret

Best Practices

Return 200 quickly — process payloads asynchronously
Verify signatures — always validate the HMAC header
Handle duplicates — use the event ID to deduplicate
Use HTTPS — plain HTTP endpoints are rejected
Monitor failures — check the dashboard for failed deliveries