Webhooks

Receive MarketBox events in your webhook endpoints

Copy page

Create a webhook endpoint to receive events at an HTTPS endpoint. After you register a webhook endpoint, MarketBox can push real-time event data to your application's webhook endpoint when events happen in your MarketBox account. MarketBox uses HTTPS to send webhook events to your app as a JSON payload that includes an Event object.

Receiving webhook events helps you respond to asynchronous events, such as when a new booking is created, a client is updated, or an order is placed.

Get started

To start receiving webhook events in your app:

1. Create a webhook endpoint handler to receive event data POST requests.
2. Create a new webhook endpoint in the MarketBox admin portal.
3. Secure your webhook endpoint.

You can register and create multiple individual endpoints for specific events.

Create a handler

Set up an HTTP or HTTPS endpoint function that can accept webhook requests with a POST method. If you're still developing your endpoint function on your local machine, it can use HTTP. After it's publicly accessible, your webhook endpoint function must use HTTPS.

Set up your endpoint function so that it:

• Handles POST requests with a JSON payload consisting of an event object.
• Quickly returns a successful status code (2xx) prior to any complex logic that might cause a timeout. For example, you must return a 200 response before updating a customer's invoice as paid in your crm system.

Example endpoint

This code snippet is a webhook function configured to check for received events from MarketBox, handle the events, and return a 200 response.

Node.js

Code
 
const express = require("express");
const crypto = require("crypto");

const app = express();

// Webhook signing secret (from your dashboard)
const WEBHOOK_SECRET = "whsec_your_webhook_secret_here";

// Use raw body so the signature can be verified
app.post("/webhook", express.raw({ type: "application/json" }), (req, res) => {
  const signature = req.headers["mb-webhook-signature"];
  const timestamp = req.headers["mb-webhook-timestamp"];
  const payload = req.body; // Buffer

  if (!signature || !timestamp) {
    return res.sendStatus(400);
  }

  // Convert raw body buffer to string
  const payloadString = payload.toString("utf8");

  // Generate expected signature
  const expectedSignature = crypto
    .createHmac("sha256", WEBHOOK_SECRET)
    .update(`${timestamp}.${payloadString}`)
    .digest("hex");

  // Verify signature
  if (signature !== `sha256=${expectedSignature}`) {
    console.log("Invalid webhook signature");
    return res.sendStatus(400);
  }

  // Parse the verified payload
  const event = JSON.parse(payloadString);

  // Handle webhook events
  switch (event.eventType) {
    case "order.created": {
      const order = event.eventData.order;
      // handleOrderCreated(order);
      break;
    }

    case "booking.created": {
      const bookings = event.eventData.bookings;
      // handleBookingCreated(booking);
      break;
    }

    case "booking.updated": {
      const bookings = event.eventData.bookings;
      // handleBookingUpdated(booking);
      break;
    }

    case "client.created": {
      const client = event.eventData.client;
      // handleClientCreated(client);
      break;
    }

    case "client.updated": {
      const client = event.eventData.client;
      // handleClientUpdated(client);
      break;
    }

    case "waitlist.created": {
      const waitlistEntry = event.eventData;
      // handleWaitlistCreated(waitlistEntry);
      break;
    }

    default:
      console.log(`Unhandled event type: ${event.event}`);
  }

  // Acknowledge receipt of the event
  res.json({ received: true });
});

Supported event types

MarketBox currently supports the following webhook event types:

Event Type	Description
order.created	Triggered when a new order is created
booking.created	Triggered when a new booking is created
booking.updated	Triggered when an existing booking is updated
client.created	Triggered when a new client is created
client.updated	Triggered when an existing client is updated
waitlist.created	Triggered when a new waitlist entry is created

Register your endpoint

After testing your webhook endpoint function, use the MarketBox admin portal to register your webhook endpoint's accessible URL so MarketBox knows where to deliver events. Registered webhook endpoints must be publicly accessible HTTPS URLs.

Webhook URL format

The URL format to register a webhook endpoint is:

Code
 
https://<your-website>/<your-webhook-endpoint>

For example, if your domain is https://mycompanysite.com and the route to your webhook endpoint is /marketbox_webhooks, specify https://mycompanysite.com/marketbox_webhooks as the Endpoint URL.

Create a webhook endpoint in the dashboard

To create a new webhook endpoint in the MarketBox admin portal:

1. Navigate to the Webhooks page in your MarketBox admin portal.
2. Click Add Webhook.
3. Enter a Name for your webhook to help identify it.
4. Optionally add a Description.
5. Select the Event Type you want to subscribe to from the dropdown.
6. Enter your Webhook URL - this must be a valid URL starting with http:// or https://.
7. Optionally add custom Headers if your endpoint requires additional authentication.
8. Click Create to save your webhook.

After creation, you'll be shown the webhook details including a secret key that you should store securely. This secret is used to verify that webhook requests are coming from MarketBox.

Secure your endpoint

After confirming that your endpoint works as expected, secure it by verifying webhook signatures.

Secure your integration by making sure your handler verifies that all webhook requests are generated by MarketBox. MarketBox includes an MB-Webhook-Signature header with each webhook request that allows you to verify the authenticity of the request.

Webhook headers

Each webhook request from MarketBox includes the following headers:

Header	Description
Content-Type	Always application/json
User-Agent	MarketBox-Webhooks/1.0
MB-Webhook-Event	The event type (e.g., order.created)
MB-Webhook-ID	A unique identifier for this webhook delivery
MB-Webhook-Timestamp	Unix timestamp when the webhook was sent
MB-Webhook-Signature	The signature for verification (format: sha256=<signature>)

Verify webhook signatures

The signature is computed using HMAC-SHA256. To verify a webhook:

1. Get the timestamp from the MB-Webhook-Timestamp header
2. Get the raw request body as a string
3. Concatenate the timestamp, a period (.), and the payload string
4. Compute the HMAC-SHA256 hash using your webhook secret
5. Compare the computed signature with the MB-Webhook-Signature header value

Node.js verification example

Code
 
const crypto = require("crypto");

function verifyWebhookSignature(payload, signature, timestamp, secret) {
  const expectedSignature = crypto
    .createHmac("sha256", secret)
    .update(`${timestamp}.${payload}`)
    .digest("hex");

  return signature === `sha256=${expectedSignature}`;
}

// In your webhook handler:
const signature = request.headers["mb-webhook-signature"];
const timestamp = request.headers["x-webhook-timestamp"];
const payload = request.body.toString();

if (!verifyWebhookSignature(payload, signature, timestamp, webhookSecret)) {
  return response.status(400).send("Invalid signature");
}

Debug webhook integrations

Multiple types of issues can occur when delivering events to your webhook endpoint:

• MarketBox might not be able to deliver an event to your webhook endpoint.
• Your webhook endpoint might have an SSL issue.
• Your network connectivity is intermittent.
• Your webhook endpoint isn't receiving events that you expect to receive.

View event deliveries

To view event deliveries, navigate to the Webhooks page in the MarketBox admin portal, then click on a webhook to view its details. The delivery logs show recent webhook deliveries including their status, HTTP response code, and response time.

Fix HTTP status codes

When an event displays a status code of 200, it indicates successful delivery to the webhook endpoint. You might also receive a status code other than 200. View the table below for a list of common HTTP status codes and recommended solutions.

Status	Description	Fix
Unable to connect	We're unable to establish a connection to the destination server.	Make sure that your host domain is publicly accessible to the internet.
302 (or other 3xx)	The destination server attempted to redirect the request. We consider redirect responses as failures.	Set the webhook endpoint destination to the URL resolved by the redirect.
400 (or other 4xx)	The destination server can't or won't process the request.	Make sure that your endpoint is publicly accessible and accepts POST requests.
500 (or other 5xx)	The destination server encountered an error while processing the request.	Review your application's logs to understand why it's returning a 500 error.
TLS error	We couldn't establish a secure connection to the destination server.	Check your SSL/TLS certificate configuration. MarketBox requires TLS v1.2 or higher.
Timed out	The destination server took too long to respond (over 10 seconds).	Make sure you defer complex logic and return a successful response immediately.

Event delivery behaviors

This section helps you understand different behaviors to expect regarding how MarketBox sends events to your webhook endpoint.

Manual retries

You can manually retry failed webhook deliveries from the MarketBox admin portal. Navigate to the webhook's delivery logs and click the retry option for any failed delivery.

Event ordering

MarketBox doesn't guarantee the delivery of events in the order that they're generated. For example, creating an order might generate the following events:

• order.created
• booking.created

Make sure that your webhook endpoint isn't dependent on receiving events in a specific order. Be prepared to manage their delivery appropriately. You can also use the API to retrieve any missing objects if needed.

Best practices for using webhooks

Review these best practices to make sure your webhook endpoints remain secure and function well with your integration.

Handle duplicate events

Webhook endpoints might occasionally receive the same event more than once. You can guard against duplicated event receipts by logging the event IDs you've processed, and then not processing already-logged events.

Use the MB-Webhook-ID header or the eventId field in the payload to identify unique events.

Only listen to event types your integration requires

Configure your webhook endpoints to receive only the types of events required by your integration. Listening for extra events puts undue strain on your server and we don't recommend it.

Handle events asynchronously

Configure your handler to process incoming events with an asynchronous queue. You might encounter scalability issues if you choose to process events synchronously. Any large spike in webhook deliveries might overwhelm your endpoint hosts.

Asynchronous queues allow you to process the concurrent events at a rate your system can support.

Receive events with an HTTPS server

If you use an HTTPS URL for your webhook endpoint (required in production), MarketBox validates that the connection to your server is secure before sending your webhook data. For this to work, your server must be correctly configured to support HTTPS with a valid server certificate. MarketBox webhooks support only TLS versions v1.2 and v1.3.

Verify events are sent from MarketBox

Verify webhook signatures to confirm that MarketBox sent the received events. MarketBox signs webhook events it sends to your endpoints by including a signature in each event's MB-Webhook-Signature header. This allows you to verify that the events were sent by MarketBox, not by a third party.

Quickly return a 2xx response

Your endpoint must quickly return a successful status code (2xx) prior to any complex logic that could cause a timeout. For example, you must return a 200 response before updating a customer's invoice as paid in your crm system.