Webhooks

Webhook management is server-side. Register and delete endpoints with the Org-API-Key from your backend, and verify deliveries on a backend HTTPS endpoint. Never manage webhooks from an app.

Webhooks push lifecycle events from Expys to an HTTPS endpoint you control, so your systems react to redemptions, point changes, member changes, and concierge messages without polling.

Register an endpoint

Create an endpoint with the events you want. The response includes the signing secret once - store it immediately; it is never returned again.

curl -X POST https://api.expys.com/v1/webhooks \
  -H "Authorization: Bearer YOUR_ORG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.yourapp.com/webhooks/expys",
    "events": ["redemption.created", "wallet.debited"]
  }'

string

required

Endpoint id (use it to delete the endpoint).

string

required

Your HTTPS delivery URL.

string[]

required

The subscribed event names.

string

required

SANDBOX or LIVE, from the key you used.

string

required

The HMAC signing secret, prefixed whsec_. Shown once - store it now.

string

required

ISO-8601 creation time.

Manage endpoints with GET /v1/webhooks (list) and DELETE /v1/webhooks/{id}. An org may hold up to 10 active endpoints per environment. See the API reference.

Event catalog

The redemption.* names cover the full booking lifecycle - one event per status transition - so a CRM sees the whole course of an experience.

Event	Fires when
`redemption.created`	A redemption is submitted.
`redemption.open`	It moves to open.
`redemption.awaiting_vendor`	It is waiting on the vendor.
`redemption.awaiting_customer`	It is waiting on the customer.
`redemption.purchased`	It is purchased (sometimes called “confirmed”; `purchased` is canonical).
`redemption.completed`	The experience completed.
`redemption.canceled`	It was canceled (points are refunded). Carries `canceledReason` and `canceledNote`.
`wallet.credited`	Points were credited to a member.
`wallet.debited`	Points were debited (for example, a redemption spend).
`member.created`	A member profile was created.
`member.tier_changed`	A member’s tier changed.
`member.removed`	A member was removed.
`interest.created`	A member registered interest in an experience. Carries the conversation id and their intake.
`interest.intake_submitted`	A member added or changed their dates, party size or contact preference.
`redemption.feedback_submitted`	A member scored a completed experience, or revised their score. Carries the rating and the comment in full.
`conversation.message_created`	A message was posted to a conversation, from either side - your member or our concierge. Branch on `authorRole`.

Subscribing to an event name not in this catalog is rejected with WEBHOOK_EVENT_UNKNOWN. A non-HTTPS or disallowed URL is rejected with WEBHOOK_URL_NOT_ALLOWED.

The `conversation.message_created` payload

Fires for a message from either side, which is what makes it useful: your backend learns when our concierge has replied, not only when your own member has written.

{
  "event": "conversation.message_created",
  "data": {
    "conversationId": "req_9f2k1x",
    "messageId": "8Kd0aQ1mZr2xWvN4pLcE",
    "author": "concierge",
    "authorRole": "CONCIERGE",
    "preview": "Your table is confirmed for 8pm - I'll send the details shortly.",
    "hasAttachments": false,
    "createdAt": "2026-09-02T18:31:04.000Z"
  }
}

Field	Notes
`authorRole`	`MEMBER` or `CONCIERGE`. The field to branch on.
`author`	The member id for a member’s message; the literal `"concierge"` for ours.
`messageId`	Fetchable through `GET /v1/conversations/{id}/messages` - the ids match.
`preview`	A truncated excerpt, capped at 140 characters. Empty for a media message, which has no text.
`hasAttachments`	`true` when the message carries files. No URL is included - fetch the message for links, which are minted fresh and short-lived.

The full message body is never sent over a webhook, only preview. Read the message itself through the API when you need it.

Internal notes never fire. Our team can leave notes on a conversation that the member does not see; those emit no event at all - including notes with files attached.

No download URL is ever sent over a webhook. Webhook payloads are retried, stored and logged by their nature, and a signed download link sitting in a log file is a publicly readable ticket for as long as it lives. hasAttachments tells you to go and read the message; the links come from there, minted fresh.

The `redemption.canceled` payload

The data object mirrors the REST redemption shape exactly, plus the externalUserID and pointsSpent a CRM needs to attribute the event:

{
  "event": "redemption.canceled",
  "data": {
    "id": "req_9f2k1x",
    "offer": "off_ba7m2k9qx1",
    "status": "canceled",
    "canceledReason": "DATE_UNAVAILABLE",
    "canceledNote": "The vendor released the date; we are sourcing another.",
    "externalUserID": "vip_1043",
    "pointsSpent": 75000000,
    "createdAt": "2026-09-01T12:00:00.000Z",
    "startAt": null,
    "endAt": null
  }
}

canceledReason and canceledNote are present on every redemption.* event, null on all of them but this one, so you never have to check the status before reading them. canceledNote is written for the member and is safe to display. See Redemptions for the six reason values.

Delivery format

Each delivery is a POST with a JSON body and these headers:

Header	Value
`X-Expys-Signature`	`sha256=<hex>` HMAC-SHA256 of the exact raw body.
`X-Expys-Timestamp`	Delivery timestamp (use to reject stale replays).
`X-Expys-Event`	The event name (for example `redemption.created`).
`X-Expys-Delivery`	A unique delivery id (use it for idempotent consumption).

Verify the signature

Recompute HMAC-SHA256 over the exact raw request body (not a re-serialized object) with your signing secret, hex-encode it, prefix sha256=, and compare in constant time against X-Expys-Signature.

import { createHmac, timingSafeEqual } from "node:crypto";

export function verifyExpysSignature(
  rawBody: string,
  signatureHeader: string,
  signingSecret: string,
): boolean {
  const digest = createHmac("sha256", signingSecret).update(rawBody, "utf8").digest("hex");
  const expected = Buffer.from(`sha256=${digest}`);
  const received = Buffer.from(signatureHeader);
  return expected.length === received.length && timingSafeEqual(expected, received);
}

import Crypto
import Foundation

func verifyExpysSignature(rawBody: Data, signatureHeader: String, signingSecret: String) -> Bool {
  let key = SymmetricKey(data: Data(signingSecret.utf8))
  let mac = HMAC<SHA256>.authenticationCode(for: rawBody, using: key)
  let expected = "sha256=" + mac.map { String(format: "%02x", $0) }.joined()

  let a = Array(expected.utf8)
  let b = Array(signatureHeader.utf8)
  guard a.count == b.count else { return false }
  var diff: UInt8 = 0
  for i in a.indices { diff |= a[i] ^ b[i] }
  return diff == 0
}

import javax.crypto.Mac
import javax.crypto.spec.SecretKeySpec

fun verifyExpysSignature(rawBody: ByteArray, signatureHeader: String, signingSecret: String): Boolean {
  val mac = Mac.getInstance("HmacSHA256")
  mac.init(SecretKeySpec(signingSecret.toByteArray(), "HmacSHA256"))
  val hex = mac.doFinal(rawBody).joinToString("") { "%02x".format(it) }
  val expected = "sha256=$hex".toByteArray()
  val received = signatureHeader.toByteArray()
  if (expected.size != received.size) return false
  var diff = 0
  for (i in expected.indices) diff = diff or (expected[i].toInt() xor received[i].toInt())
  return diff == 0
}

Read the raw body bytes before any JSON parsing middleware reshapes them. Verifying against a re-serialized object will fail because key order and whitespace differ from what was signed.

Retries and dead-lettering

A delivery is retried on any non-2xx response or timeout, with exponential backoff: first retry after 30s, doubling each time, capped at 1 hour. After 6 total attempts the delivery is dead-lettered and no longer retried.

Each delivery request times out after 10 seconds, so respond quickly. Do the real work asynchronously - acknowledge with a 2xx as soon as you have verified the signature and enqueued the event.

Consume idempotently

Deliveries are at-least-once: a retry can arrive after you already processed an event. Deduplicate on X-Expys-Delivery (or the event’s own id) and make handlers idempotent so a duplicate is a no-op.

Getting started

Catalog and pricing

Booking and members

Wallets and points

Concierge

Server-side operations

Reliability and reference

Register an endpoint

Event catalog

The `conversation.message_created` payload

The `redemption.canceled` payload

Delivery format

Verify the signature

Retries and dead-lettering

Consume idempotently

​Register an endpoint

​Event catalog

​The conversation.message_created payload

​The redemption.canceled payload

​Delivery format

​Verify the signature

​Retries and dead-lettering

​Consume idempotently

Register an endpoint

Event catalog

The `conversation.message_created` payload

The `redemption.canceled` payload

Delivery format

Verify the signature

Retries and dead-lettering

Consume idempotently