# Guide to RapidAPI Webhooks: Features and Best Practices

RapidAPI webhooks report what happens inside a RapidAPI Enterprise Hub, the private API hub companies run for their own developers and partners. An API is published, a billing plan changes, a team subscribes, a user or app key is created: each can send an HTTP request to your systems. Hub operators use these events to sync subscriptions to a CRM or billing platform, push API changes to a gateway, and plug approvals into internal workflows.

This guide covers how Enterprise Hub events are configured and tested, how to authenticate them with the hub's secret key, the events one action can set off, and what to verify yourself because RapidAPI doesn't document the payload.

## What are RapidAPI webhooks?

These webhooks belong to the **Enterprise Hub**. They are not available for the public rapidapi.com marketplace, and Hookdeck's RapidAPI source covers Enterprise Hub events only.

In the hub's Admin Panel, the **Events** tab turns event triggers on and holds up to five callback URLs. Whenever an event fires, RapidAPI sends an HTTP `POST` to every callback URL. One action often fires several events: creating an API sends API Created, API Updated, API Version Created, Billing Plan Created and Subscription Created, among others, depending on how the API is configured.

RapidAPI doesn't sign events. Every request carries the hub's secret key in the `x-rapidapi-webhook-secret` header, which RapidAPI says is there "to ensure that the request is coming from your RapidAPI Enterprise Hub".

## RapidAPI webhook features

| Feature | Details |
| --- | --- |
| Availability | Enterprise Hub only |
| Configuration | Admin Panel > **Events**: **Enable event triggers**, **Callback URL (up to 5)** |
| Fan-out | Every callback URL receives every event |
| Method | `POST` |
| Payload | Not documented. Capture one with **Test event** |
| Authentication | `x-rapidapi-webhook-secret: <secret key>`. No signature |
| Key rotation | **Generate new** |
| Testing | **Test event** per event, with a choice of callback URL |
| Monitoring | **Event logs** tab, with request and response details |
| Retries and timeout | Not documented |

## Common events

| Area | Events |
| --- | --- |
| APIs | API Created, API Updated, API Deleted, API Version Created, API Version Updated, API Version Deleted |
| Endpoints and base URLs | API Endpoint Created, Updated, Deleted; Base URL Created, Updated, Deleted (sent as Target Group events) |
| Billing plans | Billing Plan Created, Updated, Deleted |
| Subscriptions | Subscription Created, Updated, Deleted |
| Users, teams and organisations | User, Team and Organization Created, Updated, Deleted |
| Apps and keys | App Created, Updated, Deleted; App Key Created, Updated, Deleted |
| Documentation | Documentation Created, Updated, Deleted |
| Collaboration | Approval Created and Updated, Announcement Created, Discussion Created, Message Created, Discussion Comment Created |
| Jobs | Job Created, Job Updated |

RapidAPI's events table mostly uses display names like "API Created", but some rows give codes such as `BILLINGPLAN.UPDATED`, `DOCUMENTATION.DELETED`, `WORKFLOW.CREATED` and `JOBS_REQUEST.CREATED`. That hints at how the event is spelled on the wire, but RapidAPI doesn't document the request body or say which field carries the event.

The table also shows how events cascade. Deleting a subscription sends Subscription Updated. Creating a user sends App Created, App Key Created and User Created. Deleting an organisation sends Organization Deleted, Subscription Deleted, App Deleted and Team Deleted. Plan for several requests per change.

> **Inspect RapidAPI webhooks as they arrive.** Add a [Hookdeck Inspect](https://inspect.hookdeck.com) URL as a callback URL and click **Test event** to see the exact body and headers your hub sends, with no account or setup required.

## Setting up RapidAPI webhooks

1. In your Enterprise Hub, open the Admin Panel and go to the **Events** tab.
2. Slide **Enable event triggers** on.
3. Under **Callback URL (up to 5)**, click **Add a URL**, enter your endpoint, and click **Save**.
4. Copy the secret key shown for the `x-rapidapi-webhook-secret` header. Use **Generate new** if you need a fresh one.
5. Click **Test event** next to an event, choose the **Test URL**, and click **Test event** to send it.
6. Check the **Event logs** tab; **Details** shows each request and response.

RapidAPI notes that the event logs only start filling once at least one callback URL is set, even a temporary one.

To route through Hookdeck, create a source with the **RapidAPI** type and use its URL in step 3. The source has one field, **Webhook Secret**: paste the secret key from step 4. Hookdeck compares it with the `x-rapidapi-webhook-secret` header and accepts `POST`.

## Securing RapidAPI webhooks

Compare `x-rapidapi-webhook-secret` with the stored key, in constant time. There's no prefix, so compare the whole value.

```javascript
const crypto = require('crypto');
const express = require('express');

const SECRET = process.env.RAPIDAPI_WEBHOOK_SECRET;

function safeEqual(received, expected) {
  const a = Buffer.from(received, 'utf8');
  const b = Buffer.from(expected, 'utf8');
  // timingSafeEqual throws on unequal lengths, so check first.
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

const app = express();

app.post('/webhooks/rapidapi', express.raw({ type: '*/*' }), (req, res) => {
  const received = req.get('x-rapidapi-webhook-secret');
  if (!SECRET || typeof received !== 'string' || !safeEqual(received, SECRET)) {
    return res.sendStatus(401);
  }

  let event;
  try {
    event = JSON.parse(req.body.toString('utf8'));
  } catch {
    return res.sendStatus(400);
  }

  // RapidAPI doesn't document the body: capture a Test event and route on the field
  // you find there. Queue the event and respond.
  res.sendStatus(200);
});

```

The same check in Python:

```python
import hmac
import os

SECRET = os.environ.get("RAPIDAPI_WEBHOOK_SECRET", "")

def verify_rapidapi_request(headers) -> bool:
    if not SECRET:
        return False  # never accept when unconfigured
    received = headers.get("x-rapidapi-webhook-secret")
    if not received:
        return False
    # Compare bytes: compare_digest raises TypeError on a non-ASCII str.
    return hmac.compare_digest(received.encode("utf-8"), SECRET.encode("utf-8"))

```

A static secret authenticates the sender, not the body. It cannot detect a modified payload, and with no signature or timestamp a captured request can be replayed and still pass. Use HTTPS callback URLs, keep the secret out of logs, and click **Generate new** if it might have leaked, updating every receiver at the same time.

> **Make RapidAPI webhooks production-ready.** [Hookdeck Event Gateway](/event-gateway) checks the `x-rapidapi-webhook-secret` header, accepts every event from your hub, and fans it out to as many services as you need without using up the five callback URL slots.

## RapidAPI webhook limitations and pain points

### An undocumented payload

**The Problem:** You can't write a router until you've seen a request, and you can't be sure every event uses the same shape.

**Why It Happens:** RapidAPI's events page lists event names but no body, and points to **Test event** "to obtain a proper sample request".

**Workarounds:**

* Send a test for each event you handle and save the bodies as fixtures.
* Log and acknowledge any request whose event you don't recognise.

**How Hookdeck Can Help:** Every request is stored with its full body and headers in Hookdeck, so you can inspect real events and build [filters](/docs/filters) on the fields you find.

### One change, many events

**The Problem:** Creating one API triggers five or more requests, and your handler does the same work several times.

**Why It Happens:** RapidAPI fires every event an action implies, and some rows in its table list events in a different area from the action, such as Subscription Updated for a subscription deletion.

**Workarounds:**

* Make handlers idempotent, and re-read the current state from the hub API rather than trusting each event in isolation.
* Subscribe your logic to the events you need and acknowledge the rest.

**How Hookdeck Can Help:** [Deduplication](/docs/deduplication) and filters can discard events your service doesn't need, and Hookdeck delivers the rest at a rate your service can handle.

### Five callback URLs at most

**The Problem:** You want events in a CRM, a billing system, a gateway and an internal tool, and the slots run out.

**Why It Happens:** The Events tab accepts up to five callback URLs, and each receives every event.

**Workarounds:**

* Point one callback URL at a service that fans out internally.

**How Hookdeck Can Help:** One Hookdeck source can feed many [connections](/docs/connections), each with its own filter and destination, so a single callback URL serves every consumer.

### No documented retry policy

**The Problem:** An event sent while your endpoint was down may be gone.

**Why It Happens:** The Event logs tab shows each response status, but RapidAPI doesn't say whether failed requests are retried.

**Workarounds:**

* Check the Event logs after incidents.
* Reconcile important state, such as subscriptions, against the hub's API.

**How Hookdeck Can Help:** Hookdeck stores each request as it arrives and [retries](/docs/retries) delivery to your service on your schedule, and you can replay events after a fix. Hookdeck answers RapidAPI with a `200` even when the secret is wrong, but such requests are recorded as failed verification and never reach your service.

## Best practices

### Capture before you code

Use **Test event** for each event you plan to handle and keep the bodies as test fixtures.

### Rotate deliberately

**Generate new** replaces the key every callback URL receives. Update all receivers, including the Hookdeck source, in the same change.

### Deduplicate

Expect several events per change and possible repeats. See our [guide to webhook idempotency](/webhooks/guides/implement-webhook-idempotency).

### Acknowledge fast and process asynchronously

Store the event and respond, then sync downstream systems in the background. See [why to process webhooks asynchronously](/webhooks/guides/why-implement-asynchronous-processing-webhooks).

## Conclusion

RapidAPI Enterprise Hub events arrive as `POST` requests to up to five callback URLs, authenticated only by the hub's secret key in `x-rapidapi-webhook-secret`. Compare that key in constant time, capture real requests with **Test event** before you write routing code, and design for several events per change.

[Hookdeck Event Gateway](https://hookdeck.com) checks the secret, stores every event, and fans it out to all your services with retries and replay.

[Get started with Hookdeck](https://dashboard.hookdeck.com/signup) for free and handle RapidAPI webhooks reliably in minutes.