Setting up webhooks

Setting up webhooks

Webhook Integration

Ever thought about receiving a notification when a user goes through your cancellation flow?
You can easily do that with Raaft via webhooks.
Raaft’s webhooks allows you to receive events when a user goes through the cancellation flow.
Here’s a quick guide on how to set up webhooks for your Raaft app.

Steps to setup a Webhook Integration

Step 1: Generate a token

On Profile, go to Integrations.
notion image
Write a name for the webhook and paste de endpoint to which send the webhook requests.
notion image
Once you’ve done that, just click on Set Webhook.
Wait a couple of seconds and you’ll see something like the picture below.
notion image

Step 2: Receive the webhook

To correctly receive the request on the provided endpoint you need to make some actions:

1. Endpoint

First you need to set up your endpoint to receive a POST request

2. Response

When you receive a request from the webhook, it’s best practice to send back a response with a status code of 200, to avoid receiving duplicate requests due to the retry processes in place.

3. Authenticate

Before reading the data sent by the webhook, first check if the request is valid by checking the headers.
A valid request has a header property x-raaft-token whose value must be the token you generated in Step 1: Generate a token.
If the header property isn’t present or the value doesn’t match your token you must avoid reading the data sent.
Read the data only when the property is present and the value matches.

4. Read the body

After the authentication is set you can read the body content.
This will be a JSON with this structure:
{
    "appId": "your-app-id",
    "createdAt": "2024-10-07T08:10:07.558Z",
    "customer": {
        "email": "customer@email.com",
        "id": "customer-id",
        "name": "Customer Name",
        "photo": "Photo Url"
    },
    "feedback": "String with feedback",
    "flowId": "your-flow-id",
    "motivator": "Missing features or integrations",
    "outcome": "saved",
    "path": [
        {
            "stepId": 105,
            "stepType": "lossAversion"
        },
        {
            "selectedChoice": {
                "text": "Missing features or integrations",
                "type": "product",
                "choiceId": 2,
                "isSelected": false
            },
            "stepId": 106,
            "stepType": "survey"
        },
        {
            "offerName": "Switch Plans",
            "stepId": 110,
            "stepType": "offer"
        }
    ],
    "responseAccepted": {
        "name": "Switch Plans",
        "plan": {
            "amount": 8,
            "bodyText": "<h6>Basic</h6><h6><br></h6><p><b>10 </b>active users</p><p><b>8</b>&nbsp;flows</p>",
            "buttonText": "<p>Switch plan</p>",
            "currency": "USD",
            "id": "plan-id",
            "interval": "months",
            "name": "plan-name"
        },
        "timingOfChange": "period_end",
        "type": "change-plans"
    },
    "subscription": {
        "created_at": "2023-03-09T08:11:01.000Z",
        "currency": "USD",
        "customer": {
            "email": "customer@email.com",
            "id": "customer-id",
            "name": "Customer Name"
        },
        "id": "subscription-id",
        "plan": {
            "amount": 10,
            "currency": "USD",
            "id": "current-plan-id",
            "interval": "month",
            "name": "current-plan-name"
        }
    }
}
 
These are all the properties you can use:
Property
Type
Description
appId
String
Your Raaft’s app id.
createdAt
Date Object
The timestamp of the outcome generation.
customer
Object
An object containing the details of your customer, such as the email and other information provided by your payment provider if connected.
feedback
String
Text containing the feedback left by your user.
flowId
String
The id of the flow that generated the outcome.
motivator
String
The last option selected in the last survey of the flow.
outcome
String
The main value you'll want to look for, which will have a value of "canceled", "saved", "aborted", or "error" depending on the how the user exited the flow.
path
Array
An array containing the steps your user followed when navigating through the flow. Each array element is an object containing relevant information about each step.
responseAccepted
Object
The response accepted in case of a “saved” outcome. This object contains details such as the new plan accepted or the discount details, etc., that provide information about the changes applied to the subscription.
subscription
Object
The subscription details of your user in case you’ve connected your payment provider.
And you’re done! 🎉 You can now start receiving webhooks when an user goes through a flow.
âť“
If you have any issues at any point, feel free to write us at hello@raaft.io or reach out via the chat in the bottom-right corner of the screen of the app.