Portal active

Search Knowledge Base Articles

Find answers, guides, and documentation

Knowledge Base › What Are Webhooks & How They Work

What Are Webhooks & How They Work

Webhooks are automated HTTP callbacks — a way for Rackwave to push real-time event notifications to your server the moment something happens, without your application needing to ask. This article explains what webhooks are, how they differ from polling, and how the Rackwave webhook system is architected.

Webhooks vs Polling — The Core Difference

Polling (Pull) Webhooks (Push)
How it works Your server repeatedly asks the API: "Has anything changed?" Rackwave calls your server instantly when something changes
Latency Depends on poll interval — data can be minutes stale Near real-time — typically within 1–3 seconds of the event
API usage High — hundreds or thousands of GET requests per hour Zero — no outbound requests needed from your server
Efficiency Poor — most polls return no new data Excellent — only fires when something actually happens
Implementation Simple — just call the API on a timer Requires a publicly accessible HTTPS endpoint on your server
Best for Low-frequency checks or when a public endpoint is not possible Production integrations needing real-time delivery status updates

How Rackwave Webhooks Work — Step by Step

  1. You register a webhook endpoint URL in the platform dashboard (MigoSMTP or Telnxo) or in the Rackwave portal for subscription events.
  2. You select which event types you want to receive (e.g. email.delivered, sms.delivered, invoice_paid).
  3. When a subscribed event occurs — such as an email being delivered — the platform's webhook dispatcher fires immediately.
  4. Rackwave makes an HTTP POST request to your registered endpoint URL, sending a JSON payload describing the event.
  5. Rackwave includes an HMAC-SHA256 signature in the request headers so you can verify the payload is genuine.
  6. Your endpoint processes the payload and responds with HTTP 200 OK within the timeout window (30 seconds).
  7. If your endpoint does not return a 200 within 30 seconds, Rackwave marks the delivery as failed and schedules a retry.

Webhook Payload Structure

Every webhook payload follows this consistent structure:

{
  "event":      "email.delivered",
  "product":    "migosmtp",
  "platform_id": "1",
  "timestamp":  "2026-06-07T09:39:00Z",
  "data": {
    "message_id":   "msg_8f3a2b1c9d4e7f0a",
    "to":           "recipient@example.com",
    "from":         "hello@yourdomain.com",
    "subject":      "Your order has shipped",
    "status":       "delivered",
    "delivered_at": "2026-06-07T09:38:55Z"
  }
}
Field Description
event The event type string — always use this to route the payload in your handler
product Platform that fired the event: migosmtp, telnxo, or rackwave
platform_id Internal platform ID from the Rackwave portal
timestamp ISO 8601 UTC timestamp of when the event occurred
data Event-specific payload — structure varies per event type (see Webhook Event Types Reference)

Retry Policy

If your endpoint does not return HTTP 200 within 30 seconds — due to a timeout, error, or server unavailability — Rackwave automatically retries the delivery:

Attempt Delay After Previous Attempt Cumulative Time
1 (initial) Immediate 0 seconds
2 5 minutes ~5 minutes
3 30 minutes ~35 minutes
4 2 hours ~2 hours 35 min
5 8 hours ~10 hours 35 min
Final 24 hours after initial attempt Marked as permanently failed — no further retries
Respond first, process second: Your endpoint should return HTTP 200 immediately upon receiving the webhook, then process the payload asynchronously. If heavy processing (database writes, third-party API calls) happens before responding, you risk timing out and triggering unnecessary retries.

Security — Why Webhooks Must Be Verified

Your webhook endpoint is a public URL — anyone who knows it could send fake payloads. Rackwave signs every webhook with an HMAC-SHA256 signature using your webhook secret. Always verify this signature before processing the payload to ensure it genuinely came from Rackwave.

See: Verifying webhook signatures (HMAC)

Idempotent Webhook Handling

In rare cases — such as network issues during delivery — your endpoint may receive the same event more than once. Design your webhook handler to be idempotent:

  • Use the data.message_id or event ID as a unique key.
  • Before processing, check whether you have already handled this event ID.
  • If yes, return HTTP 200 immediately without re-processing.
  • This prevents duplicate database writes, duplicate notifications, or double-billing.

Next Steps

Did you find this article useful?
Related Articles