Open dashboard

Webhooks

Rekaz sends notifications for business events to the HTTPS endpoint configured for your tenant. Each tenant can have one receiver.

Configure a receiver

In the Rekaz dashboard, open Settings > API Keys > Webhook. Enter a publicly reachable HTTPS URL, enable outbound webhooks, and save. Copy the signing secret and store it only on your server.

Accept JSON POST requests and return a 2xx response promptly. Queue the work so your receiver can acknowledge the delivery before processing it.

Every delivery includes Content-Type: application/json, User-Agent: RekazWebhookClient/1.0, and X-Rekaz-Signature. The signature is an HMAC-SHA256 value encoded as lowercase hexadecimal.

Payload and casing

Webhook fields use PascalCase, including fields in nested objects. The envelope contains Id, EventName, CreatedAt, and Data. Transaction, reservation, subscription, and merchandise order events include customer details in Data.Customer: Id, Name, MobileNumber, Email, NationalId, and CustomFields. Gift events use BuyerCustomer and RecipientCustomer. Enum values are strings.

Use Id, the unique delivery ID, to deduplicate deliveries. EventName identifies the event type and determines which Data fields to expect. CreatedAt is the UTC time when the webhook was created; Data contains the current resource snapshot.

Accept unknown fields and nullable properties so your handler keeps working when new fields are added. All date-time values are UTC, including the Formatted date and time fields. Reservation payloads carry TimeZone, the store's IANA time zone such as Asia/Riyadh: convert StartDate and EndDate to it to show local times.

Customer ID number and custom fields

Customer.NationalId is the ID number saved in Rekaz's built-in national ID field. It is null when the store doesn't fill it. A store that collects the ID through its own custom field sends it in Customer.CustomFields instead.

Customer.CustomFields lists the customer's own custom fields, the ones the store adds to the customer form, such as an ID or residency number. Each item has Name, Label, Type, and Value. Name is the field's fixed identifier and never changes; Label is what the store calls it and can be renamed. Match on Name. Ask the store for the Name of the field you need, or read it from a delivery whose Label matches. The list is empty or null when the customer has no values.

Payload examples

Transaction webhook delivery

All five transaction events use the Data shape below. Read the customer's mobile number from Data.Customer.MobileNumber. Transaction REST API responses use camelCase fields and flat customer details, so they need separate parsing.

For booking confirmation messages, handle ReservationConfirmedEvent and read Data.Customer.MobileNumber. TransactionCreatedEvent reports a new transaction, and ReservationUpdatedEvent reports a reservation change. Neither confirms a booking. Use the envelope's Id to deduplicate retries.

{
"Id": "083bc1f5-d7e9-44b2-9a53-94129a9f763a",
"EventName": "TransactionCreatedEvent",
"CreatedAt": "2026-08-25T10:00:00Z",
"Data": {
"Id": "4ef86c8e-2c63-4c73-a3f0-df124e71c210",
"TransactionNumber": 1254,
"InvoiceNumber": 987,
"Status": "Completed",
"PaymentStatus": "Paid",
"Source": "Internal",
"Customer": {
"Id": "69e943fc-5705-44d8-a2da-f23371a1625d",
"Name": "Ahmed Ali",
"MobileNumber": "+966500000000",
"Email": "ahmed@example.com",
"NationalId": "1012345678",
"CustomFields": [
{
"Name": "5f2c8a41-7d3e-4b9a-a6c1-2e8f0d4b7c93",
"Label": "File number",
"Type": "Number",
"Value": 4821
}
]
},
"BranchIds": [
"4c31f35e-7477-4887-8ea8-93a3d13581ec"
],
"Subtotal": 100,
"DiscountAmount": 10,
"TaxAmount": 13.5,
"FeesAmount": 0,
"TotalAmount": 103.5,
"PaidAmount": 103.5,
"RemainingAmount": 0,
"Currency": "SAR",
"ExchangeRateToSAR": 1,
"CreatedAt": "2026-08-25T10:00:00Z",
"UpdatedAt": "2026-08-25T10:05:00Z",
"Items": [
{
"Id": "b3ec6432-283f-4c69-8897-2791192ff1e0",
"Type": "Reservation",
"NameAr": "\u062d\u062c\u0632 \u0627\u0633\u062a\u0634\u0627\u0631\u0629",
"NameEn": "Consultation reservation",
"Sku": "CONSULT-01",
"ProductId": "ee73af19-cfb6-44b6-a06a-d9805112a80a",
"PriceId": "ec62375d-cd99-47ed-bb9c-b7027c195423",
"Quantity": 1,
"UnitPrice": 100,
"Subtotal": 100,
"DiscountAmount": 10,
"TaxAmount": 13.5,
"TotalAmount": 103.5
}
],
"Payments": [
{
"Id": "bc908f57-0f5d-4178-8903-42d82a98c7ee",
"Type": "Payment",
"Status": "Confirmed",
"Method": "Online",
"CustomPaymentMethodId": null,
"Amount": 103.5,
"Currency": "SAR",
"PaymentDate": "2026-08-25T10:05:00Z"
}
]
}
}

Transaction REST API responses

Both pages include 200 response examples with customer details, totals, items, and payments.

Reservation webhook delivery

All reservation event names use this Data shape. EventName identifies the lifecycle change.

{
  "Id": "6c4a9c47-b9ec-4f5d-9fb7-8a356d577dc4",
  "EventName": "ReservationConfirmedEvent",
  "CreatedAt": "2026-08-25T10:02:00Z",
  "Data": {
    "Id": "4d5399df-58a5-4523-a347-f5cb691e42d1",
    "StartDate": "2026-08-25T10:00:00Z",
    "FromDay": "Monday",
    "FormattedFromDate": "2026-08-25",
    "FormattedFromTime": "10:00 AM",
    "EndDate": "2026-08-25T11:00:00Z",
    "EndDay": "Monday",
    "FormattedEndDate": "2026-08-25",
    "FormattedEndTime": "11:00 AM",
    "TimeZone": "Asia/Riyadh",
    "Status": "Confirmed",
    "CustomStatus": null,
    "Price": 103.5,
    "Discount": 10,
    "Customer": {
      "Id": "69e943fc-5705-44d8-a2da-f23371a1625d",
      "Name": "Ahmed Ali",
      "MobileNumber": "+966500000000",
      "Email": "ahmed@example.com",
      "NationalId": "1012345678",
      "CustomFields": [
        {
          "Name": "5f2c8a41-7d3e-4b9a-a6c1-2e8f0d4b7c93",
          "Label": "File number",
          "Type": "Number",
          "Value": 4821
        }
      ]
    },
    "ProductName": "Consultation",
    "PriceName": "Standard",
    "OptionName": "Standard",
    "Number": "4821",
    "CancellationReason": null,
    "Sku": "CONSULT-01",
    "Providers": [
      {
        "Name": "Sara Ahmed",
        "Number": 42,
        "Id": "b7e7f9ab-21a0-4d36-9958-e8cb0e4a6c14"
      }
    ],
    "BranchId": "4c31f35e-7477-4887-8ea8-93a3d13581ec",
    "BranchNameAr": "فرع الرياض",
    "BranchNameEn": "Riyadh Branch",
    "ProductId": "ee73af19-cfb6-44b6-a06a-d9805112a80a",
    "ProductCategoryId": "a27585a7-aef7-44f7-85a9-bebec6601ce4",
    "OptionId": "ec62375d-cd99-47ed-bb9c-b7027c195423",
    "CustomFields": [
      {
        "Name": "notes",
        "Label": "Notes",
        "Type": "String",
        "Value": "First visit"
      }
    ],
    "Items": [
      {
        "PriceName": "Standard",
        "PriceId": "ec62375d-cd99-47ed-bb9c-b7027c195423",
        "OptionName": "Standard",
        "OptionId": "ec62375d-cd99-47ed-bb9c-b7027c195423",
        "Sku": "CONSULT-01",
        "Price": 103.5
      }
    ],
    "Order": {
      "Id": "4ef86c8e-2c63-4c73-a3f0-df124e71c210",
      "SequentialNumber": 1254,
      "Status": "Confirmed",
      "PaymentStatus": "Paid",
      "Currency": "SAR",
      "Subtotal": 100,
      "DiscountAmount": 10,
      "TaxAmount": 13.5,
      "TotalAmount": 103.5,
      "PaidAmount": 103.5,
      "RemainingAmount": 0,
      "Item": {
        "Id": "b3ec6432-283f-4c69-8897-2791192ff1e0",
        "ProductId": "ee73af19-cfb6-44b6-a06a-d9805112a80a",
        "PriceId": "7d1f6a52-3c0e-4b88-9a4d-5e2b8c91f0a3",
        "OptionId": "ec62375d-cd99-47ed-bb9c-b7027c195423",
        "ReferenceId": "4d5399df-58a5-4523-a347-f5cb691e42d1",
        "Sku": "CONSULT-01",
        "Quantity": 1,
        "UnitPrice": 100,
        "Subtotal": 100,
        "DiscountAmount": 10,
        "TaxAmount": 13.5,
        "TotalAmount": 103.5
      }
    },
    "InvoiceUrl": "https://platform.rekaz.io/orders/last/invoice?orderId=4ef86c8e-2c63-4c73-a3f0-df124e71c210&isPrint=false"
  }
}

Subscription webhook delivery

Subscription events use this Data shape. SubscriptionTransferedEvent also includes FromCustomer and ToCustomer. Other subscription events omit these fields.

{
  "Id": "763e88c8-5bc6-4f09-b90c-34ab7f34ad49",
  "EventName": "SubscriptionTransferedEvent",
  "CreatedAt": "2026-08-25T11:00:00Z",
  "Data": {
    "Id": "8e126099-555d-4a22-99e0-72b35c53e17d",
    "StartDate": "2026-08-01T00:00:00Z",
    "EndDate": "2026-09-01T00:00:00Z",
    "Status": "Transferred",
    "Price": 200,
    "Discount": 20,
    "Customer": {
      "Id": "23167f7e-64ac-499e-8991-dfa0d3876de0",
      "Name": "Mona Saleh",
      "MobileNumber": "+966511111111",
      "Email": "mona@example.com"
    },
    "Name": "Monthly membership",
    "Number": "2084",
    "Code": "SUB-2084",
    "CustomFields": [
      {
        "Name": "goal",
        "Label": "Goal",
        "Type": "String",
        "Value": "Improve fitness"
      }
    ],
    "PausedAt": null,
    "ResumeAt": null,
    "BranchId": "4c31f35e-7477-4887-8ea8-93a3d13581ec",
    "BranchNameAr": "فرع الرياض",
    "BranchNameEn": "Riyadh Branch",
    "Items": [
      {
        "PriceName": "Monthly",
        "PriceId": "ec62375d-cd99-47ed-bb9c-b7027c195423",
        "OptionName": "Monthly",
        "OptionId": "ec62375d-cd99-47ed-bb9c-b7027c195423",
        "Price": 200
      }
    ],
    "InvoiceUrl": "https://platform.rekaz.io/orders/last/invoice?orderId=1c7e068d-0152-4249-9fe1-c5baf2a8e939&isPrint=false",
    "FromCustomer": {
      "Id": "69e943fc-5705-44d8-a2da-f23371a1625d",
      "Name": "Ahmed Ali",
      "MobileNumber": "+966500000000",
      "Email": "ahmed@example.com"
    },
    "ToCustomer": {
      "Id": "23167f7e-64ac-499e-8991-dfa0d3876de0",
      "Name": "Mona Saleh",
      "MobileNumber": "+966511111111",
      "Email": "mona@example.com"
    }
  }
}

Merchandise order webhook delivery

All merchandise-order event names use this Data shape. EventName identifies whether the order was created, completed, or canceled.

{
  "Id": "9dcb11b9-1887-4b4d-8729-df8490a3fd18",
  "EventName": "MerchandiseOrderCreatedEvent",
  "CreatedAt": "2026-08-25T12:00:00Z",
  "Data": {
    "Id": "3ac6f6dd-8890-4c88-abf6-e27be67330ac",
    "BranchId": "4c31f35e-7477-4887-8ea8-93a3d13581ec",
    "BranchNameAr": "فرع الرياض",
    "BranchNameEn": "Riyadh Branch",
    "Status": "Pending",
    "CustomStatus": null,
    "TotalPrice": 230,
    "Discount": 20,
    "Code": "MER-3108",
    "Customer": {
      "Id": "69e943fc-5705-44d8-a2da-f23371a1625d",
      "Name": "Ahmed Ali",
      "MobileNumber": "+966500000000",
      "Email": "ahmed@example.com"
    },
    "CreationTime": "2026-08-25T12:00:00Z",
    "Items": [
      {
        "Id": "8cf0a9b9-0de1-4664-b462-bef40a57fc33",
        "Name": "Black - Large",
        "ProductName": "Rekaz T-shirt",
        "ProductId": "dbef7a15-f3fb-4d58-bcf9-b86d92d21115",
        "PriceName": "Large",
        "PriceId": "54285793-ab49-4dc7-a1eb-f9dbf8a61da5",
        "Quantity": 2,
        "TotalPrice": 230,
        "Discount": 20,
        "CustomFields": [
          {
            "Name": "color",
            "Label": "Color",
            "Type": "List",
            "Value": "Black"
          }
        ]
      }
    ],
    "InvoiceUrl": "https://platform.rekaz.io/orders/last/invoice?orderId=45a92d55-38ed-4cf3-9e16-0246af07d8ce&isPrint=false"
  }
}

Gift webhook delivery

All gift event names use this Data shape. EventName identifies whether the gift was created, activated, redeemed, or cancelled.

{
  "Id": "bc28cb6d-9f97-4b84-8d9a-743a62af608d",
  "EventName": "GiftActivatedEvent",
  "CreatedAt": "2026-08-25T13:00:00Z",
  "Data": {
    "Id": "aa124ca3-4c63-4746-84c0-9403a5a50f1a",
    "BranchId": "4c31f35e-7477-4887-8ea8-93a3d13581ec",
    "BranchNameAr": "فرع الرياض",
    "BranchNameEn": "Riyadh Branch",
    "Status": "Active",
    "CustomStatus": null,
    "TotalPrice": 250,
    "CreationTime": "2026-08-25T13:00:00Z",
    "ProductId": "5f510bf2-cc24-4d09-a8a2-f2f7778f25d2",
    "ProductName": "Gift card",
    "PriceId": "79333b43-4e22-46ec-b9d0-65cbf668f158",
    "PriceName": "SAR 250",
    "Message": "Happy birthday!",
    "FromName": "Ahmed",
    "ToName": "Mona",
    "Language": "ar",
    "ShowBuyerInfo": true,
    "GiftThemeName": "Celebration",
    "GiftCardImageUrl": "https://cdn.rekaz.io/example/gift-card.png",
    "GiftCouponCode": "GIFT-7R2Q",
    "RedemptionUrl": "https://example.rekaz.io/gifts/redeem/example-token",
    "InvoiceUrl": "https://platform.rekaz.io/orders/last/invoice?orderId=f9743b47-2c5b-43cb-8e8f-2897eef1711d&isPrint=false",
    "BuyerCustomer": {
      "Id": "69e943fc-5705-44d8-a2da-f23371a1625d",
      "Name": "Ahmed Ali",
      "MobileNumber": "+966500000000",
      "Email": "ahmed@example.com"
    },
    "RecipientCustomer": {
      "Id": "23167f7e-64ac-499e-8991-dfa0d3876de0",
      "Name": "Mona Saleh",
      "MobileNumber": "+966511111111",
      "Email": "mona@example.com"
    },
    "CustomFields": []
  }
}

Transaction events

Event Meaning
TransactionCreatedEvent Transaction created
TransactionUpdatedEvent Transaction or pending payment changed
TransactionPaidEvent Payment confirmed
TransactionRefundedEvent Payment refunded
TransactionCancelledEvent Transaction cancelled

TransactionUpdatedEvent covers pending payment creation, editing, and deletion. TransactionPaidEvent reports confirmed payments.

Other event names

Reservation

  • ReservationCreatedEvent
  • ReservationConfirmedEvent
  • ReservationDoneEvent
  • ReservationCancelledEvent
  • ReservationUpdatedEvent

Subscription

  • SubscriptionCreatedEvent
  • SubscriptionActivatedEvent
  • SubscriptionCancelledEvent
  • SubscriptionExpiredEvent
  • SubscriptionPausedEvent
  • SubscriptionResumedEvent
  • SubscriptionPauseScheduledEvent
  • SubscriptionTransferedEvent
  • SubscriptionUpdatedEvent

Use the event name SubscriptionTransferedEvent exactly as shown, with one r in Transfered.

Merchandise orders

  • MerchandiseOrderCreatedEvent
  • MerchandiseOrderCompletedEvent
  • MerchandiseOrderCanceledEvent

Gifts

  • GiftCreatedEvent
  • GiftActivatedEvent
  • GiftRedeemedEvent
  • GiftCancelledEvent

Reservation pricing and order totals

Price and Items[].Price contain the reservation line total after discount, including tax. Both fields remain available for existing integrations.

The Order object provides Subtotal, DiscountAmount, TaxAmount, TotalAmount, PaidAmount, RemainingAmount, Currency, OrderStatus, OrderPaymentStatus, and the related Item breakdown.

Order.Item includes Quantity, UnitPrice, Subtotal, DiscountAmount, TaxAmount, and TotalAmount. The reservation Price matches Order.Item.TotalAmount. Order.TotalAmount can differ when the order contains other items.

Identify the service and price

Map services on ProductId and OptionId. Both stay the same when the store edits the product.

  • ProductId identifies the service that was booked.
  • OptionId identifies its price. Order.Item.OptionId, the top-level OptionId and Items[].OptionId have the same value, and Items[].PriceId currently equals it. In GET /api/public/products the same value is pricing[].immutableId.
  • Order.Item.PriceId is different: it is the id of the price version the order was placed on. Rekaz creates a new price version each time the store saves the product, so this value changes with every save and the version it points to can later be deleted. Don't map services on it, and don't expect it to equal OptionId. Likewise, use pricing[].immutableId from the products API, not pricing[].id.

Verify the signature

Read the raw request bytes before parsing JSON. Compute HMAC-SHA256 over those exact bytes using the webhook signing secret. Encode the result as lowercase hexadecimal and compare it with X-Rekaz-Signature using a constant-time comparison. Reject a missing or invalid signature before processing the payload.

Regenerating the secret in Settings > API Keys > Webhook immediately changes the secret used for new delivery attempts. Update your receiver before rotating when possible. Keep the secret and full customer payloads out of logs.

A valid signature confirms that the request came from Rekaz. Check the resource's current state before taking sensitive actions.

Delivery behavior

Any 2xx response acknowledges a delivery. Failed deliveries may be retried; do not rely on a specific retry schedule. Your receiver must handle duplicates and events arriving out of order.

Store Id with a unique constraint before applying side effects. Fetch the resource through the authenticated API when you need its current state.