Webhooks

​

Events

​

Currently Supported

• FormSubmission - Triggers when a form is submitted by a contact.

​

Coming Soon

These webhook events will soon be available to help you trigger external workflows based on real-time activity within the Fello platform.

• Dashboard Viewed
  Fires when a contact views their dashboard.
• Dashboard CTA Clicked
  Fires when a contact clicks any call-to-action in their dashboard.
• Email CTA Clicked
  Fires when a contact clicks a call-to-action in an email.
• Postcard Scanned
  Fires when a contact scans a postcard or manually enters its URL.
• Contact Unsubscribed
  Fires when a contact opts out of future communications.
• Tag Added
  Fires when one or more tags are added to a contact.
• Tag Removed
  Fires when one or more tags are removed from a contact.
• Contact Enriched
  Fires when new data is appended to a contact record.
• Contact Info Updated
  Fires when a contact’s personal details (e.g., name, email) are updated.
• Assigned User Changed
  Fires when the contact’s assigned user is changed.
• Note Added
  Fires when a new note is added to a contact’s timeline.

​

Registering a Webhook

Send a POST request over HTTPS to the /v1/webhooks endpoint, providing a JSON payload that includes both the event name and the callback URL.

Each webhook registration would return a subscriptionId which can be used to delete the webhook later.

​

Receiving Webhook Events

In your application, create an endpoint that can handle HTTP POST requests at the URL specified during webhook registration. The request body will contain JSON data. To confirm receipt, respond within 10 seconds using a 2XX status code such as 200 or 204. Any other response indicates that the webhook was not received, prompting our system to retry at varying intervals for up to 8 hours.

For instance, an endpoint at might receive a POST request like this when a form is submitted in Fello:

POST /fello/callback/formsubmission HTTP/1.1
Content-Type: application/json
...
{
    "events": [
        {
            "eventType": "FormSubmission",
            "eventDate": "2024-01-01T00:00:00.000Z",
            "data": {
                "formData": {
                    "firstName": "<name>",
                    "lastName": "<lastName>",
                    "phone": "<phone>",
                    ....
                }
            }
        }
    ]
}

​

Signature Validation

We strongly recommend verifying the signature to ensure it is Fello who is making the webhook call. Each Fello App comes with client secret which client can use to validate the webhook requests.

Request from Fello will include fello-webhook-signature header which can be used for HMAC based signature verification.

Sample code for validating signature in different languages is drafted below.

const crypto = require("crypto");
const json = {
    "events": []
}
// request body -- note that it is an unformatted json string
const body = JSON.stringify(json);

// prepare a concatenated payload -- which we will sign
const clientSecretFromFello = "<<your secret>>";

const signatureFromFelloHeaders = "<<fello webhook signature header >>";

// this function will generate signature and compare with fello
function isRequestFromFello(signedContent, signatureFromFello, clientSecret) {
    const secretBytes = Buffer.from(clientSecret, "base64");
    const mySignature = crypto
        .createHmac("sha256", secretBytes)
        .update(signedContent)
        .digest("base64");
    return signatureFromFello === mySignature;
}

if (isRequestFromFello(body, signatureFromFelloHeaders, clientSecretFromFello)) {
    // do stuff
    console.log("Yes");
} else {
    // reject request
    console.log("No");
}

​

Deleting a Webhook

In order to disable a webhook manually, you need to call the DELETE event for/v1/webhooks/ with the corresponding ID for your registered webhook.

​

Failures

Your webhook endpoint should respond quickly—within 5 seconds—with a 200 or 204 status. If the request times out or returns any other status code, our system will retry for 4 hours, post that message would be lost.

​

Testing Webhooks

Because webhooks need a publicly accessible URL, testing them locally can be challenging. We recommend using a service like Webhook.site during development to simulate and verify webhook requests.