Open dashboard
View page as Markdown

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, and Email. 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.

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"
},
"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",
    "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"
    },
    "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": "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.

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.