Webhooks

What are Webhooks?

Webhooks are automated messages sent from your marketplace to external systems when specific events occur. Think of them as real-time notifications that let other applications know something happened.

Common Use Cases

Available Events

Subscribe to any combination of these events when creating a webhook endpoint:

Booking lifecycle: when does each event fire?

Use this timeline to decide which events to subscribe to. A single booking can fire multiple events over its lifetime.

What the panel looks like

A simplified view of an endpoint's configuration: pick which events fire, copy the signing secret to verify requests on your end, and watch deliveries succeed or retry.

Creating a Webhook Endpoint

Follow these steps to set up a webhook endpoint:

Webhook Security

Each webhook endpoint receives a unique signing secret. Use this to verify that incoming requests are genuinely from Prometora and haven't been tampered with.

Webhook Payload

Webhook requests are sent as HTTP POST with a JSON body. Every event uses the same envelope —id, type,createdAt, storeId, and a data block whose shape depends on the event type.

Example: booking.created

{
  "id": "evt_8a3f7c2d9e1b4a6f8c2d9e1b4a6f1234",
  "type": "booking.created",
  "createdAt": "2026-04-23T14:22:11.823Z",
  "storeId": "66f1a2b3c4d5e6f7a8b9c0d1",
  "data": {
    "bookingId": "66f4e5d6c7b8a9f0e1d2c3b4",
    "bookingNumber": "CON-1745418131-A3KZ7Q",
    "status": "pending",
    "bookingType": "service",
    "livemode": true,
    "listing": {
      "id": "66f2c3d4e5f6a7b8c9d0e1f2",
      "title": "Deep Clean — 3 Bedroom"
    },
    "buyer": {
      "id": "66f3b4c5d6e7f8a9b0c1d2e3",
      "email": "[email protected]",
      "firstName": "Marie",
      "lastName": "Tremblay",
      "name": "Marie Tremblay"
    },
    "pricing": {
      "currency": "cad",
      "total": 18000,
      "originalTotal": 20000,
      "discount": 2000,
      "couponCode": "SPRING10"
    },
    "schedule": {
      "serviceDate": "2026-05-01",
      "serviceTimeSlot": "09:00 - 12:00",
      "serviceDuration": 180,
      "serviceAddress": "123 Rue Sainte-Catherine, Montréal, QC"
    },
    "message": "Please focus on the kitchen",
    "payment": {},
    "createdAt": "2026-04-23T14:22:11.823Z",
    "updatedAt": "2026-04-23T14:22:11.823Z"
  }
}

All prices are sent in cents of the store's currency (so 18000 means CA$180.00). The livemode flag is true for real customer bookings andfalse when Stripe test keys were used — add a filter in your automation so test bookings don't leak into production flows.

Event-specific fields:

• booking.payment_succeeded — adds a populated payment block (stripePaymentIntentId, stripeSessionId, paidAt) and status becomes "confirmed".
• booking.cancelled — adds cancellation: { cancelledBy, refundIssued }. cancelledBy is one of "buyer", "seller", or "owner".
• booking.declined — adds decline: { reason } from the seller's decline message.

Delivery Logs

Every webhook delivery is logged so you can see exactly what happened. Expand the "Recent Deliveries" section on any webhook to view:

• Status: Success (green) or failure (red) badge with HTTP status code
• Event type: Which event triggered the delivery
• Response time: How long your endpoint took to respond (in milliseconds)
• Retry indicator: Shows "Retry #1" or "Retry #2" for retried deliveries
• Timestamp: When the delivery was attempted

Delivery logs are kept for 7 days. The 10 most recent deliveries are shown per endpoint.

Automatic Retries

If a delivery fails (your endpoint returns a non-2xx status code or times out), Prometora will automatically retry the delivery up to 2 more times with increasing delays:

The exact same payload is resent on each retry, so your endpoint will receive identical data. Each retry attempt appears as a separate entry in the delivery logs.

Auto-Disable Protection

To protect both your system and ours, webhooks are automatically disabled after 10 consecutive failures. This prevents repeated delivery attempts to endpoints that are consistently unreachable.

Managing Webhooks

Enable/Disable

Toggle webhooks on or off without deleting them. Disabled webhooks won't receive any events.

View Activity

Each webhook shows when it was last triggered and how many consecutive failures have occurred. Expand "Recent Deliveries" to see detailed delivery history.

Delete

Remove webhook endpoints you no longer need. This action cannot be undone.

Integration Examples

Prometora webhooks are a standard HTTP POST with a JSON body, so they work with any automation platform. Below are step-by-step recipes for the most common setups.

Top Automation Recipes