🧳Managing Webhooks

Learn how to manage various aspects of Airstack webhooks for your application, from webhook creation, receiving payload, etc.

Create New Webhook

Currently, there is no dedicated API to update an existing webhook. If you would like to make changes to your webhook, you should first delete your webhook and create a new one with a new configuration.

You can simply call the /webhooks API as shown below to create a new webhooks with the receiving endpoint and filter configuration provided to the body request.

To learn more about filter configuration, check this section here.

curl -X 'POST' \
  'https://webhooks.airstack.xyz/api/v1/webhooks' \
  -H 'accept: application/json' \
  -H 'Authorization: <YOUR_AIRSTACK_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
  "endpoint": "YOUR_ENDPOINT",
  "filter_config": {
    "event_type": "profile.updated"
    }
  }
}'

// Prerequisites: npm install axios
import axios from 'axios';

const url = 'https://webhooks.airstack.xyz/api/v1/webhooks';
const headers = {
  'accept': 'application/json',
  'Authorization': 'YOUR_AIRSTACK_API_KEY',
  'Content-Type': 'application/json'
};
const data = {
  endpoint: 'YOUR_ENDPOINT', // your endpoint
  filter_config: {
    event_type: 'profile.updated', // Listen to all profile updates
  }
};

axios.post(url, data, { headers })
  .then(response => {
    console.log(response.data);
  })
  .catch(error => {
    console.error('There was an error!', error);
  });

// Prerequisites: npm install axios
const axios = require('axios');

const url = 'https://webhooks.airstack.xyz/api/v1/webhooks';
const headers = {
  'accept': 'application/json',
  'Authorization': 'YOUR_AIRSTACK_API_KEY',
  'Content-Type': 'application/json'
};
const data = {
  endpoint: 'YOUR_ENDPOINT', // your endpoint
  filter_config: {
    event_type: 'profile.updated', // Listen to all profile updates
  }
};

axios.post(url, data, { headers })
  .then(response => {
    console.log(response.data);
  })
  .catch(error => {
    console.error('There was an error!', error);
  });

{
  "webhook_id": "01HYDYEBHMANSVJ0JKSVK9W3VY",
  "portal_link": "https://apiserver.instance-fm94fpopa.hc-fhtewk6q9.us-east-2.aws.f2e0a955bb84.cloud/portal?token=am4AdjH0bz67JDDTRwNesZMO",
  "authentication": {
    "header_name": "x-airstack-webhook",
    "header_value": "G85wBFVT1EH7OWrs"
  },
  "status": true, // indicates the your webhook has been successfully created
  "message": "Successfully created subscription"
}

Receiving Payload From Webhooks

To receive data payload from webhooks, you will need to have a POST endpoint where you can receive the payload in the body:

import express, { Request, Response } from "express";
import bodyParser from "body-parser";

const app = express();

app.use(bodyParser.json());

app.post("/webhook", (request: Request, response: Response) => {
  console.log(request.body);

  // Add your business logic here

  response.status(200).json("Success");
});

app.listen(4000, () => console.log("Running on port 4000"));

const express = require("express");
const bodyParser = require("body-parser");

const app = express();

app.use(bodyParser.json());

app.post("/webhook", (request, response) => {
  console.log(request.body);

  // Add your business logic here

  response.status(200).json("Success");
});

app.listen(4000, () => console.log("Running on port 4000"));

{
  "id": "b9f62fdc493d1e0033b79dee9102fbe9f72e820e8acece4b6b9d21b2a4240b31",
  "eventTimestamp": "2024-05-11T08:43:50.531Z",
  "dappName": "farcaster",
  "dappSlug": "farcaster_v3_optimism",
  "blockchain": "optimism",
  "userId": "3761",
  "userAddress": "0xa3a736379bfb4a9748c3e4daf5f9af0edfcc6c1a",
  "userAssociatedAddresses": [
    "0xa3a736379bfb4a9748c3e4daf5f9af0edfcc6c1a",
    "Cry3MBYMS34p67Tr6pmart85JuTpdULhgDtaV8rxadng",
    "0xcbfbcbfca74955b8ab75dec41f7b9ef36f329879"
  ]
}

Then, simply add your business logic before returning status 200 and your endpoint is ready to receive data payload from AIrstack webhooks.

This endpoint have to be accessible through the internet, so if you are developing locally, you should expose your endpoint by creating a secure tunnel with service such as ngrok.

To create a secure tunnel with ngrok, simply run the following command:

ngrok http 4000 # Or replace with the PORT for your endpoint

This will provide you with a tunnel URL that you can provide as an endpoint when creating the webhook.

Once your endpoint is ready for production, simply deploy it to your preferred hosting platform.

Validating Filter Configuration

Filter configuration has 3 available fields:

event_type (Required): specify the type of events on Farcaster network to listen to, check out the list here.
filter: specify to filter based on the available filter field and the value specified. For profile.created and profile.updated events, check out ProfileFilter. For follow.created and follow.deleted events, check out FollowFilter.
payload: Only required if filter field exist. This field accepts a sample payload which needs to have the same field value for fields specified in filter, while others can have arbitrary value. For profile.created and profile.updated events, check out ProfilePayload. For follow.created and follow.deleted events, check out FollowPayload.

In order to ensure that your webhooks are created successfully, it is best practice that you validate your filter configuration as shown below:

In payload, ensure that the value of fields matched to the value provided in filter field. Other fields that is not provided in filter field can just use arbitrary value in payload.

Otherwise, if this is not fulfilled, validation will fail.

curl -X 'POST' \
  'http://webhooks.airstack.xyz/api/v1/filters/test' \
  -H 'accept: application/json' \
  -H 'Authorization: <YOUR_AIRSTACK_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "event_type": "follow.deleted",
    "filter": {
      "followerProfileId": "3761"
    },
    "payload": {
      "followerProfileId": "3761",
      "followingProfileId": "326089"
    }
  }'

// Prerequisites: npm install axios
import axios from 'axios';

const url = 'http://webhooks.airstack.xyz/api/v1/webhooks';
const headers = {
  'accept': 'application/json',
  'Authorization': 'YOUR_AIRSTACK_API_KEY',
  'Content-Type': 'application/json'
};
const data = {
  endpoint: 'https://webhook.site', // your endpoint
  filter_config: {
    event_type: 'follow.deleted', // Listen to all unfollow events
    filter: {
      followerProfileId: "3761"
    },
    payload: {
      followerProfileId: "3761",
      followingProfileId: "326089"
    }
  }
};

axios.post(url, data, { headers })
  .then(response => {
    console.log(response.data);
  })
  .catch(error => {
    console.error('There was an error!', error);
  });

// Prerequisites: npm install axios
const axios = require('axios');

const url = 'http://webhooks.airstack.xyz/api/v1/webhooks';
const headers = {
  'accept': 'application/json',
  'Authorization': 'YOUR_AIRSTACK_API_KEY',
  'Content-Type': 'application/json'
};
const data = {
  endpoint: 'https://webhook.site', // your endpoint
  filter_config: {
    event_type: 'follow.deleted', // Listen to all unfollow events
    filter: {
      followerProfileId: "3761"
    },
    payload: {
      followerProfileId: "3761",
      followingProfileId: "326089"
    }
  }
};

axios.post(url, data, { headers })
  .then(response => {
    console.log(response.data);
  })
  .catch(error => {
    console.error('There was an error!', error);
  });

{
  "success": true
}

Delete Webhook

To delete an existing webhook, simply run the following code and provide the webhook ID associated with the webhook that would like to be deleted:

curl -X 'DELETE' \
  'http://webhooks.airstack.xyz/api/v1/webhooks/<webhook_id>' \
  -H 'accept: application/json' \
  -H 'Authorization: <YOUR_AIRSTACK_API_KEY>'

// Prerequisites: npm install axios
import axios from "axios";

const url = "http://webhooks.airstack.xyz/api/v1/webhooks/<webhook_id>";
const headers = {
  accept: "application/json",
  Authorization: "YOUR_AIRSTACK_API_KEY",
};

axios
  .delete(url, { headers })
  .then((response) => {
    console.log("Webhook deleted successfully:", response.data.message);
  })
  .catch((error) => {
    console.error("There was an error!", error);
  });

// Prerequisites: npm install axios
const axios = require("axios");

const url = "http://webhooks.airstack.xyz/api/v1/webhooks/<webhook_id>";
const headers = {
  accept: "application/json",
  Authorization: "YOUR_AIRSTACK_API_KEY",
};

axios
  .delete(url, { headers })
  .then((response) => {
    console.log("Webhook deleted successfully:", response.data.message);
  })
  .catch((error) => {
    console.error("There was an error!", error);
  });

{
  "message": "Webhook deleted successfully",
  "status": true
}

Developer Support

If you have any questions or need help regarding managing Airstack webhooks, please join our Airstack's Telegram group.

More Resources

PreviousQuickstart NextProfile Creation

Last updated 15 days ago