​
Events

​
Currently Supported

  • FormSubmission - Triggers when a form is submitted by a contact.
  • DashboardClick - Triggers when a contact clicks a CTA in their dashboard.
  • EmailClick - Triggers when a contact clicks a CTA in an email.
  • PostcardScan - Triggers when a contact visits a postcard’s URL, either by scanning it or entering it manually.
  • ContactUnsubscribed - Triggers when a contact opts out of further communications.
  • ContactEnriched - Triggers when a contact is enriched with new data.
  • ContactDetailsUpdated - Triggers when a contact’s personal information (e.g., name, email,phone) is updated.

​
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.
  • 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.
  • 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.
There is a limit of 3 webhooks that can be registered for each event.
Callback URLs must point to a secure (HTTPS) endpoint.
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.
Fello will automatically unsubscribe failing webhooks after multiple unsuccessful attempts. You will be notified by email if this occurs.

​
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.