Webhook 101: Understanding Rise.ai Webhooks

What You'll Find HereWebhooks are automated, real-time notifications that Rise.ai sends to your application as an HTTP POST request. These requests are triggered when specific events occur within a merchant's Rise.ai account, such as a new gift card being created or a wallet action being updated. By "consuming" these webhooks, your application can stay in sync with Rise.ai data and execute logic based on those events. Webhook setup differs for merchants and third-party app partners, so start by choosing the setup path that matches your integration.

Webhook Setup PathsRise supports two webhook setup models: merchant self-serve configuration and third-party app partner configuration. The delivery payload is similar, but the way the webhook URL is configured is different.

Merchants: self-serve webhook setupA merchant can enable and configure webhooks directly from their Rise admin:

• Open Developer Tools: Click Developer Tools in the Rise admin menu.• Go to Webhooks: Open the Webhooks page.• Create webhook: Click Create webhook, select the event, and enter the callback URL.• Repeat per event: Create a separate webhook subscription for each event the merchant wants to send.

Third-party apps: configured by RiseThird-party app partners do not self-register merchant webhook URLs in the Rise admin and there is no programmatic webhook registration API for partner apps today.

• Onboarding: Contact Rise support or your Rise partner contact with the webhook URL or URLs you want to receive events on.• Event subscriptions: Share the specific events your app needs, such as Gift card created or Store credit issued.• Development testing: We recommend opening a test merchant account while developing. In that account, you can use Developer Tools > Webhooks to create test subscriptions and send sample deliveries with the Test webhook button.• Shared endpoint model: For OAuth multi-merchant apps, Rise configures webhook delivery at the app level. Your app should expect events from multiple merchants on the configured endpoint.• Merchant routing: Webhook deliveries include instanceId and eventType in the parsed delivery data. Use instanceId to map each event to the merchant installation captured during OAuth.

🎧 How to Consume and Parse WebhooksConsuming webhooks is a multi-step process that involves receiving the request, verifying and parsing its contents, and responding correctly.

Webhook Consumption Process

Set Up Your Webhook EndpointExpose a public HTTPS URL that can receive HTTP POST requests and register it with Rise.ai.

Receive the POST RequestWhen an event occurs, Rise.ai sends an HTTP POST request to your callback URL.

Verify and Parse the PayloadVerify the JWT signature, decode the payload, and parse the nested event data before processing it.

Send a 200 OK ResponseImmediately return HTTP 200 OK to acknowledge receipt. Process complex operations in background jobs.

Detailed Webhook Integration Steps

1. Set Up Your Webhook EndpointYour application must expose a public HTTPS URL that can receive HTTP POST requests. Merchants configure this URL from Developer Tools > Webhooks. Third-party app partners provide their URL or URLs to Rise support during onboarding.

2. Receive the POST RequestWhen an event occurs, Rise.ai sends an HTTP POST request to your endpoint. Treat the request body as a signed webhook payload, not as a raw API response object.

3. Verify and Parse the PayloadVerify the JWT signature with the Rise public key before trusting the payload. After decoding, parse the delivery data to read instanceId, eventType, and the nested Domain Event object.

4. Send a 200 OK ResponseThis is critical. To acknowledge that you have successfully received the webhook, your endpoint must return an HTTP 200 OK status code. Important: Send this response immediately after receiving and parsing the data. Perform any complex processing (like database updates or API calls) in a background job or queue. If Rise.ai doesn't receive a 200 OK quickly, it may consider the delivery a failure and retry, leading to duplicate processing on your end.

📄 Understanding the Webhook Payload StructureWebhook payloads are not one-to-one matches for GET API responses. Rise sends the request body as a signed JWT. The decoded JWT contains a stringified delivery object, and that delivery object contains another stringified Domain Event object with the event-specific data.

Common Delivery FieldsAfter verifying and decoding the request, these fields are important for routing and event handling:

• decoded.data: A JSON string containing the webhook delivery object.• decoded.iat / decoded.exp: JWT issued-at and expiration timestamps.• instanceId: The unique installation ID for the merchant site. Third-party apps should use this to route the event to the correct merchant account.• eventType: The webhook event type that was delivered, such as wix.rise.v1.gift_card_initialized.• identity: A stringified JSON object describing the identity that triggered the event, such as an APP identity and appId.• data: A JSON string containing the nested Domain Event object.• id: The unique Domain Event ID inside the parsed event object. Use this to detect and ignore duplicate events.• entityFqdn: The fully qualified name of the entity type, such as wix.rise.v1.gift_card.• slug: The action that occurred, such as initialized, updated, disabled, or expired.• entityId: The unique ID of the Rise entity that was affected.• eventTime: The UTC timestamp of when the event occurred.• event.entityAsJson: A stringified JSON representation of the entity or sample entity data included in the event.

Parsing ExampleFor Node.js integrations, the parsing flow looks like this after signature verification:

const decoded = jwt.verify(req.body, risePublicKey);
const delivery = JSON.parse(decoded.data);
const domainEvent = JSON.parse(delivery.data);
const identity = delivery.identity ? JSON.parse(delivery.identity) : null;
const entity = domainEvent.event?.entityAsJson
  ? JSON.parse(domainEvent.event.entityAsJson)
  : null;

const instanceId = delivery.instanceId;
const eventType = delivery.eventType;
const idempotencyKey = domainEvent.id;
const entityId = domainEvent.entityId;

Entity data is nested differently from API responses

• Stringified JSON: decoded.data, delivery.identity, delivery.data, and domainEvent.event.entityAsJson are strings that should be parsed before use.• Gift card events: For gift card events, use eventType and entityFqdn to identify the event, then parse domainEvent.event.entityAsJson when present.• Test deliveries: The Test webhook button can send sample entity data. Use it to validate parsing, routing, signature verification, and idempotency handling.• Authoritative state: Call the relevant GET API when you need the latest full resource state after receiving a webhook.

⭐ Key Best Practices for Reliable Webhook HandlingThe provided documentation highlights two critical features for building a robust integration.

1. Handle Duplicates with the Event ID"Event ID. With this ID you can easily spot duplicated events and ignore them."Network issues can cause Rise.ai to send the same webhook more than once. Your application must be idempotent (i.e., processing the same request multiple times has no additional effect).How to implement:

• Check ID: When you receive a webhook, check its id (the Event ID).• Verify Processing: Look in your database or cache to see if you have already processed this id.• Skip if Processed: If yes, skip processing and just send a 200 OK.• Save if New: If no, process the event and then save the id as "processed" before finishing.

2. Handle Event Order with the Sequence Number"A sequence number that indicates the order of updates to an entity... You can use this number to make sure you're handling updates in the right order. Just save the latest sequence number on your end and compare it to the one in each new message. If the new message has an older (lower) number, you can safely ignore it."Webhooks can arrive out of order. For example, an "update" event might arrive before the "created" event for the same entity. The entityEventSequence solves this.How to implement:

• Store Sequence: For each entityId (e.g., a specific Wallet ID), store the entityEventSequence of the last event you processed for it.• Compare on Arrival: When a new event for that entityId arrives, compare its entityEventSequence to the one you have stored.• Ignore Old Events: If the new sequence number is lower or equal to the stored one, it's an old, out-of-order event. Ignore it and send a 200 OK.• Process New Events: If the new sequence number is higher, process the event and update the stored sequence number for that entityId.

📋 Available Gift Card and Store Credit WebhooksThe following gift-card and store-credit events are available for merchant webhook setup and for partner app subscriptions configured by Rise:

🎁 Gift Card

• Gift card created: Fired when a gift card is created.• Gift card updated: Fired when a gift card is updated.• Gift card disabled: Fired when a gift card is disabled.• Gift card balance adjusted: Fired when a gift card balance changes.

💳 Store Credit

• Store credit issued: Fired when store credit is issued to a customer.• Store credit expired: Fired when store credit expires.

📱 App Instance

• App Instance Installed: For OAuth app partners, fired when a merchant installs your app. Store the instanceId from the OAuth/install flow and use it to route future webhook deliveries.

Need these events for a third-party app?Send Rise support your callback URL or URLs and the event names you want to receive. Rise will configure the partner app subscriptions for you.

⚠️ Important Distinction: Webhooks vs. Workflow TriggersIt's easy to confuse consuming webhooks with reporting events for workflows.

Webhooks (Rise.ai → Your App)

• What it is: Rise.ai sends you a POST request when something happens in Rise (e.g., Gift Card Created).• Your Role: You consume this data to react to events.

Workflow Triggers (Your App → Rise.ai)

• What it is: Your app sends Rise.ai a POST request (POST /workflows/v1/events/report) to report an event that happened in your app (e.g., "Return Approved").• Your Role: You produce this data to trigger an automation workflow inside the Rise.ai platform.