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.

🎧 How to Consume and Parse WebhooksConsuming webhooks is a multi-step process that involves receiving the request, 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 containing a JSON payload with event details.

Parse the JSON PayloadRead and parse the request body from JSON string into a native object for your programming language.

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 (an "endpoint") that can receive HTTP POST requests. You will register this URL with Rise.ai (the provided documentation implies this is done during the app configuration process with your Rise contact).

2. Receive the POST RequestWhen an event occurs, Rise.ai will send an HTTP POST request to your endpoint. The body of this request will contain a JSON payload with all the event details.

3. Parse the JSON PayloadYour endpoint's code needs to read the raw body of the request and parse it from a JSON string into a native object or data structure for your programming language. • Node.js (Express): If you use a framework like Express with a body-parsing middleware (express.json()), the payload will be readily available as request.body. • Python (Flask): You can get the parsed JSON data using request.get_json().

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 StructureAll event webhooks (like Wallet Action Created or Gift Card Updated) share a common "Event Data" structure.

Common Payload FieldsHere are the key top-level fields you'll find in almost every webhook payload:

• id: The unique Event ID. You must use this to detect and ignore duplicate events.• entityFqdn: The fully qualified name of the entity type (e.g., rise.wallet_action).• slug: The name of the action that occurred (e.g., created, updated, deleted).• entityId: The unique ID of the Rise.ai entity that was affected (e.g., the specific WalletAction ID).• eventTime: The UTC timestamp (ISO-8601 format) of when the event occurred.• entityEventSequence: A sequence number for updates to a specific entity. Crucial for handling event order.• [eventName]Event: A nested object containing the event details. The name changes based on the slug (e.g., createdEvent, updatedEvent, actionEvent).

Example: 'Wallet Action Created' PayloadBased on the documentation, a Wallet Action Created webhook payload would look like this:

{
  "id": "evt_12345EXAMPLE",
  "entityFqdn": "rise.wallet_action",
  "slug": "created",
  "entityId": "wa_98765EXAMPLE",
  "eventTime": "2020-04-26T13:57:50.699Z",
  "triggeredByAnonymizeRequest": false,
  "originatedFrom": null,
  "entityEventSequence": "1678886400123",
  "createdEvent": {
    // This object (defined as EntityCreatedEvent)
    // would contain the data for the newly created Wallet Action.
  }
}

⭐ 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 Webhooks in the DocumentationBased on the provided text, here are the webhooks you can consume:

📱 App Instance

• App Instance Installed: Fired when a merchant installs your app. The documentation notes this is a primary way to obtain the instanceId required for making API calls on behalf of that merchant.

💳 Wallet Action

• Wallet Action Created: When a new wallet action is created• Wallet Action Deleted: When a wallet action is deleted• Wallet Action Disabled: When a wallet action is disabled• Wallet Action Expired: When a wallet action expires• Wallet Action Started: When a wallet action starts• Wallet Action Updated: When a wallet action is updated

🎁 Gift Card

• Gift Card Added: When a gift card is added• Gift Card Created: When a new gift card is created• Gift Card Disabled: When a gift card is disabled• Gift Card Initialized: When a gift card is initialized• Gift Card Updated: When a gift card is updated

🧑 Recipient

• Recipient Created: When a new recipient is created• Recipient Deleted: When a recipient is deleted

🛒 Gift Card Order

• Gift Card Order Created: When a gift card order is created• Gift Card Order Deleted: When a gift card order is deleted• Gift Card Order Updated: When a gift card order is updated

⚠️ 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.