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.

➡️
OpenAPI Specification for the Webhooks Provisioning API domain
Get the OpenAPI Specification (formerly Swagger), which is a standardized format that describes the functionalities, endpoints, parameters, and data models of this API in a JSON file here.

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

Parameter	Type	Description
`event`	string	The event you want to subscribe to (e.g., "orders.created")
`url`	string	Your endpoint URL that will receive webhook payloads
`is_active`	boolean	Whether the webhook should be active (optional, defaults to true)

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

Parameter	Type	Description
`event`	string	Update the event type (optional)
`url`	string	Update the webhook URL (optional)
`is_active`	boolean	Enable or disable the webhook (optional)

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:

Parameter	Description	Example
`event`	Filter by event type	`?event=orders.created`
`url`	Filter by URL	`?url=https://example.com`
`is_active`	Filter by active status	`?is_active=true`

Supported Events

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