Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.neynar.com/llms.txt

Use this file to discover all available pages before exploring further.

Neynar webhooks are a way to receive real-time updates about events on the Farcaster protocol. You can use webhooks to build integrations that respond to events on the protocol, such as when a user creates a cast or when a user updates their profile. This guide will show you how to set up a webhook in the Neynar developer portal and how to integrate it into your application. To create a new webhook without writing any code, head to the neynar dashboard and go to the webhooks tab. Click on the new webhook and enter the details as such:
The webhook will fire to the specified target_url. To test it out, we are using a service like ngrok to create a public URL that will forward requests to your local server. However, we recommend using your own domain to avoid interruptions.

​
Free endpoints like ngrok, localtunnel, etc. throttle webhook deliveries, best to use your own domain

Let’s create a simple server that logs out the event. We will be using Bun JavaScript. 
const server = Bun.serve({
  port: 3000,
  async fetch(req) {
    try {
      console.log(await req.json());

      return new Response("gm!");
    } catch (e: any) {
      return new Response(e.message, { status: 500 });
    }
  },
});

console.log(`Listening on localhost:${server.port}`);
Next: run bun serve index.ts, and run ngrok with ngrok http 3000. Copy the ngrok URL and paste it into the “Target URL” field in the Neynar developer portal. The webhook will call the target URL every time the selected event occurs. Here, I’ve chosen all the casts created with farcasterframesbot present in the text. Now the server will log out the event when it is fired. It will look something like this: 
{
  created_at: 1708025006,
  type: "cast.created",
  data: {
    object: "cast",
    hash: "0xfe7908021a4c0d36d5f7359975f4bf6eb9fbd6f2",
    thread_hash: "0xfe7908021a4c0d36d5f7359975f4bf6eb9fbd6f2",
    parent_hash: null,
    parent_url: "chain://eip155:1/erc721:0xfd8427165df67df6d7fd689ae67c8ebf56d9ca61",
    root_parent_url: "chain://eip155:1/erc721:0xfd8427165df67df6d7fd689ae67c8ebf56d9ca61",
    parent_author: {
      fid: null,
    },
    author: {
      object: "user",
      fid: 234506,
      custody_address: "0x3ee6076e78c6413c8a3e1f073db01f87b63923b0",
      username: "balzgolf",
      display_name: "Balzgolf",
      pfp_url: "https://i.imgur.com/U7ce6gU.jpg",
      profile: [Object ...],
      follower_count: 65,
      following_count: 110,
      verifications: [ "0x8c16c47095a003b726ce8deffc39ee9cb1b9f124" ],
      active_status: "inactive",
    },
    text: "LFG",
    timestamp: "2024-02-15T19:23:22.000Z",
    embeds: [],
    reactions: {
      likes: [],
      recasts: [],
    },
    replies: {
      count: 0,
    },
    mentioned_profiles: [],
  },
}

​
Conclusion

That’s it, it’s that simple! The next steps would be to have a public server that can handle the webhook events and use it to suit your needs. Lastly, make sure to sure what you built with us on Farcaster by tagging @neynar and if you have any questions, reach out to us on warpcast or Slack!