---
updatedAt: 2026-09-06T20:14:10.000Z
agentTools:
  projectIndex: https://docs.rekaz.io/llms.txt
---

# 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.

```json
{
"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

* [List transactions](https://docs.rekaz.io/legacy/reference/getpublictransactionlist) returns `{ "items": [...], "totalCount": 1 }`.
* [Get a transaction by ID](https://docs.rekaz.io/legacy/reference/getpublictransaction) returns one transaction object.

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.

```json
{
  "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.

```json
{
  "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.

```json
{
  "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.

```json
{
  "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.