> ## Documentation Index
> Fetch the complete documentation index at: https://learn.nexudus.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 📡 Marketplace Webhooks

> Learn how Nexudus sends real-time notifications to your marketplace application

When you register a marketplace application and provide a Webhook URL, Nexudus will send real-time notifications to that endpoint whenever certain events occur. This allows your service to stay synchronized with inventory and booking changes without needing to poll the API.

## How Webhooks Work

Nexudus sends `POST` requests to your Webhook URL with a JSON payload. Your endpoint must:

* Always return `application/json` content-type
* Always return HTTP status `200`
* Support `https://` (webhooks are only sent to HTTPS URLs)
* Respond within 5 seconds (requests will timeout after this)

<Warning>
  Webhooks are sent asynchronously and may be retried if your endpoint fails to respond. Ensure your endpoint is idempotent and can handle duplicate notifications.
</Warning>

## Types of Webhooks

Nexudus sends two types of webhook notifications to marketplace applications:

### 1. Feed Webhooks

Feed webhooks notify your application that inventory data has changed and your service should refresh its data by fetching the feed or calendar endpoint.

**When they're sent:**

* A plan is created, updated, or deleted
* A product is created, updated, or deleted
* A resource is created, updated, or deleted
* A marketplace installation status is changed (enabled/disabled or settings updated)

**Payload:**

```json theme={null}
{
  "marketplace_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "type": "feed",
  "calendar_url": "https://{domain}/api/apps/marketplaceapplications/calendar?marketplace_id={marketplace_id}&location_id={location_id}",
  "feed_url": "https://{domain}/api/apps/marketplaceapplications/feed?marketplace_id={marketplace_id}&location_id={location_id}"
}
```

| Field            | Type   | Description                                                   |
| ---------------- | ------ | ------------------------------------------------------------- |
| `marketplace_id` | string | Your unique marketplace application identifier                |
| `type`           | string | Always `"feed"` for feed webhooks                             |
| `calendar_url`   | string | URL to fetch calendar data for this marketplace and location  |
| `feed_url`       | string | URL to fetch full feed data for this marketplace and location |

### 2. Booking Webhooks

Booking webhooks notify your application of real-time changes to reservations. These are sent only for locations where your marketplace has the **"Provide Resources"** option enabled.

**When they're sent:**

* A new reservation is created → `type: "bookingnew"`
* An existing reservation is updated → `type: "bookingupdate"`
* A reservation is cancelled or deleted → `type: "bookingdelete"`

**Payload:**

```json theme={null}
{
  "booking": {
    "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "from_time": "2025-08-15T09:00:00Z",
    "to_time": "2025-08-15T10:00:00Z",
    "from_time_local": "2025-08-15T11:00:00",
    "to_time_local": "2025-08-15T12:00:00",
    "customer": {
      "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
    },
    "resource": {
      "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "name": "Meeting Room A"
    },
    "floor_plan_item": {
      "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "name": "Desk 3"
    }
  },
  "type": "bookingnew"
}
```

| Field                          | Type     | Description                                                              |
| ------------------------------ | -------- | ------------------------------------------------------------------------ |
| `booking.id`                   | string   | Unique identifier for the reservation                                    |
| `booking.from_time`            | datetime | Start time in UTC                                                        |
| `booking.to_time`              | datetime | End time in UTC                                                          |
| `booking.from_time_local`      | datetime | Start time in the location's local timezone                              |
| `booking.to_time_local`        | datetime | End time in the location's local timezone                                |
| `booking.customer.id`          | string   | Unique identifier for the customer (may be null for unassigned bookings) |
| `booking.resource.id`          | string   | Unique identifier for the resource                                       |
| `booking.resource.name`        | string   | Display name of the resource                                             |
| `booking.floor_plan_item.id`   | string   | Unique identifier for the desk/unit in the floor plan (may be null)      |
| `booking.floor_plan_item.name` | string   | Display name of the desk/unit (may be null)                              |
| `type`                         | string   | One of: `bookingnew`, `bookingupdate`, `bookingdelete`                   |

## Webhook Delivery Details

* **Content-Type**: All webhook requests are sent with `Content-Type: application/json`
* **Timeout**: Requests timeout after 5 seconds
* **Retry behavior**: Failed webhook deliveries are logged but not automatically retried
* **Async delivery**: Webhooks are sent asynchronously via background jobs, so there may be a short delay (typically a few seconds) between the event and the webhook delivery

## Testing Your Webhook Endpoint

You can test your webhook endpoint before publishing your marketplace application. Nexudus will send webhook notifications to your URL even while your application is unpublished, as long as it's installed on your own location.

We recommend using a service like [webhook.site](https://webhook.site) or [requestbin.com](https://requestbin.com) during development to inspect incoming webhook payloads.

## Related Pages

* [➕ Registering a marketplace](/rest-api/marketplaces/registering-a-marketplace)
* [📖 Marketplace API overview](/rest-api/marketplaces/overview)