Intro to Webhooks

Overview

When you create a webhook, Rackbeat will automatically send HTTP POST requests to your specified URL whenever the subscribed events occur. This enables you to build real-time integrations and keep your systems synchronized with Rackbeat data.

Authentication

All webhook API requests require proper authentication using your API key:

Authorization: Bearer {YOUR_AUTH_KEY}
Content-Type: application/json
Accept: application/json

Creating a Webhook

To create a new webhook, send a POST request to the webhooks endpoint:

Endpoint

POST /api/webhooks

Required Parameters

Request Example

{
  "event": "orders.created",
  "url": "https://your-app.com/webhooks/rackbeat/orders",
  "is_active": true
}

Response Example

{
  "webhook": {
    "id": 123,
    "event": "orders.created",
    "url": "https://your-app.com/webhooks/rackbeat/orders",
    "is_active": true,
    "plugin": null,
    "failures_since_last_success": 0,
    "token": "abc123def456ghi789jkl012mno345pq",
    "created_at": "2025-01-08 10:30:00",
    "updated_at": "2025-01-08 10:30:00"
  }
}

Important Notes

• The token field is only returned when creating a new webhook. Store this token securely - it will be sent in the Rackbeat-Webhook-Token header with every webhook request for verification.
• If a webhook with the same event and url already exists, the existing webhook will be updated instead of creating a duplicate.
• URLs must be valid and accessible from the internet (local URLs are only allowed in development environments).

Retrieving Webhooks

List All Webhooks

GET /api/webhooks

This returns a paginated list of all your webhooks.

Get Specific Webhook

GET /api/webhooks/{webhook_id}

Updating Webhooks

You can update existing webhooks to change their configuration:

Endpoint

PUT /api/webhooks/{webhook_id}

Parameters

Example

{
  "is_active": false
}

Deleting Webhooks

To remove a webhook:

DELETE /api/webhooks/{webhook_id}

Webhook Filtering

You can filter webhooks when listing them using query parameters:

Supported Events

Rackbeat supports webhooks for numerous events across different modules. For a complete list of supported events, see the Webhook Events Reference.