# Welcome!

Welcome to Nodefy! We're pumped you're here!

### What is Nodefy?

Nodefy provides ready-to-use notifications in a single, unified API.  

### Why should I care about notifications?

Notifications are crucial to engage and retain your users. They provide relevant information in a timely, reliable, and convenient way. Notifications can be a huge source of value to both you and your users. Unfortunately, a good notification system takes significant resources away from building your core product. And no one likes a bad notification system. 

That's why we've designed Nodefy to provide notifications that both you and your users will love.

### Why Nodefy?

We're building Nodefy so you can implement advanced notifications in your app \*without\* the extra code, maintenance costs, and hassle of building your own system in-house.

### How will Nodefy improve my product?

Nodefy's comprehensive set of webhooks, filters and integrations enable:

* Better user engagement
* Improved scalability
* More efficient data handling
* More time to build cool stuff

### How can I get support?

Send a tweet or DM at [Nodefy](https://x.com/nodefy_xyz)

Send an email to <rj@nodefy.xyz>

Cast to our [Farcaster channel](https://warpcast.com/~/channel/Nodefy)


# Quickstart

Start exploring Nodefy's functionality

**Step 1: Create Your Account**

* Email <rj@nodefy.xyz> for a developer account and API access

**Step 2: Review documentation**

* Familiarize yourself with our [API Guide](/our-api-guide/overview)
* Reach out with any questions related to your use case &#x20;

**Step 3: Configure Your Notifications**

* Use the API to configure your notification settings.


# Use Cases

Discover how you can use Nodefy to enhance your app's notifications

### **Example Use Cases**

* Payment confirmations for contractor payments / payroll app
* Sales and portfolio updates for white-label NFT platform
* Transaction trackers for a crypto exchange
* Notifications from the onset for an embedded wallets provider
* Airdrop and yield alerts for DeFi users
* New proposal notice for DAO members


# Supported Blockchains

The future is multichain. Please reach out to request new blockchain compatibility.

Nodefy currently supports notifications for events on:

* Ethereum
* Base
* Optimism
* Arbitrum
* Polygon
* zkSync
* Farcaster protocol

<figure><img src="https://1936782662-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FflAA0xqEHKNJ7R9sTrSt%2Fuploads%2FbooERp6iqDdEGMfQTMia%2Fimage.png?alt=media&amp;token=1bc329ef-6d3b-4b72-8648-2cae549f378b" alt=""><figcaption></figcaption></figure>

EVM chains testnets (e.g. Sepolia) are also supported. Your users will receive consistent notifications even if events are settled on different chains.


# Overview

Learn about the core concepts to get familiar with Nodefy structure

Before you start building with the Nodefy API, it's helpful to understand the following core concepts:

### Webhooks

Webhooks are triggered when certain onchain events occur on the blockchain networks you're monitoring. These events could include:

* Token transfers
* Smart contract function calls
* NFT minting or sales
* ...and more

Nodefy lets you create webhooks to listen for these events, and when a webhook is triggered, it sends a notification to your users through the channels you have configured.

### Filters

Filters allow you to refine the conditions under which a webhook is triggered. You can specify criteria such as:

* Token type
* Transaction value
* Specific addresses or contract functions

By applying filters, you can ensure that notifications are only sent for the events that are truly relevant to your users.

### Actions

Actions are the steps taken when a webhook is triggered and its associated filters are met. Nodefy offers a variety of built-in actions, including:

* Sending email notifications
* Sending Telegram messages
* Posting to Slack channels
* Calling custom webhooks (for more flexibility building event-driven systems)

You can configure different actions for different webhooks, allowing you to tailor the notification experience to your specific needs.


# Authentication

Getting and managing your API keys

To access the Nodefy API, you'll need a valid API key.&#x20;

### How to Obtain Your API Key

To request an API key, please contact our team at <rj@nodefy.xyz>. We'll work with you to understand your specific use case and provide you with an API key.

### Using Your API Key

Once you receive your API key, include it in the `Authorization` header of each request you make to the Nodefy API. Use the Bearer authentication scheme:

```http
Authorization: Bearer YOUR_API_KEY 
```

#### Example (cURL):

```bash
curl -X GET 'https://api.nodefy.xyz/api/v1/webhooks/' \
     -H 'Authorization: Bearer YOUR_API_KEY'
```

### Important Considerations

* **Never share your API key publicly.** Treat your API key as a confidential password.
* **Security:** We recommend using HTTPS to protect your API key during transmission. Additionally, consider storing your API key in an environment variable or secure configuration file rather than directly in your code.

### Error Handling

If your API key is invalid or missing, you will receive a `401 Unauthorized` error response:

```json
{
  "error": "Unauthorized",
  "message": "Invalid or missing API key"
}
```


# Notification API Methods

Comprehensive list of endpoints to create and manage your notification system.

#### POST Endpoint

{% content-ref url="/pages/2jkwBl7QPN8tLRSjxK18" %}
[Create a notification](/our-api-guide/notification-api-methods/create-a-notification)
{% endcontent-ref %}

#### GET Endpoint

{% content-ref url="/pages/cwx88r3d284VkdK1aYwC" %}
[Fetch a user's notifications](/our-api-guide/notification-api-methods/fetch-a-users-notifications)
{% endcontent-ref %}

#### DELETE Endpoint

{% content-ref url="/pages/oUYKZmgApQYtyWpCOhT9" %}
[Delete a notification](/our-api-guide/notification-api-methods/delete-a-notification)
{% endcontent-ref %}


# Create a notification

This endpoint lets you create a new notification.

### Endpoint:

<pre class="language-http"><code class="lang-http"><strong>POST /api/v1/nodefy/notifications/
</strong></code></pre>

### Headers:

```json
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

### Request Body:

```json
{
    "external_user_id": str,                // Unique ID of the user to receive the notification
    "channel": "EMAIL"|"WEBHOOK"|"TELEGRAM"|"SLACK", // Notification channel
    "notification_name": str,               // optional
    "template": text,                       // optional
    "delivery_location": str,               // Recipient address (e.g. email address, telegram ID)
    "event_details": {
        "network": str,                     // Blockchain network
        "event_type": str,                  // Type of event to monitor
        "addresses": [str],                 // Array of single 0x address
        "filters": [                        // optional: Array of filter objects
            { "field_name": str, "operator": str, "value": str, "value_type": str },
            # ... more filters if needed
        ],
        "graphql": {                         // only for graphql webhook
            "topic_0": str, // optional,
            "topic_1": str, // optional
            "topic_2": str, // optional
            "topic_3": str // optional
        },
    }
}
```

### Example Request Body:

This creates an email notification to <user@example.com> for any ETH transactions incoming or outgoing from wallet 0x123...abc.

{% code fullWidth="false" %}

```json
{
    "external_user_id": "user123",
    "channel": "EMAIL", 
    "notification_name": "My ETH Notification",
    "delivery_location": "user@example.com",
    "event_details": {
        "network": "ETH_MAINNET",
        "event_type": "ADDRESS_ACTIVITY",
        "addresses": ["0x123...abc"],
        "filters": [
            { "field_name": "asset", "operator": "eq", "value_type": "str", "value": "ETH" } 
        ]
    }
}

```

{% endcode %}

(See the "[Defining Events](/our-api-guide/defining-event-types)" section for details on specific `event_type` parameters)

(See the "[Using Filters](/our-api-guide/using-filters)" section for details on `filters`)

### Response (Success):

Returns a unique identifier for the notification.

```
{
  "notification_id": 123         
}
```


# Fetch a user's notifications

This endpoint lets you retrieve a list of all active notifications you've created with your API key.

### Endpoint:

```http
GET /api/v1/nodefy/notifications/
```

### Headers:

```json
Authorization: Bearer YOUR_API_KEY
```

### Response (Success):

```json
[
  {
    "id": 123,                             // Notification ID (integer)
    "external_user_id": "user123",         // External user ID
    "channel": "EMAIL",                    // Notification channel
    "notification_name": "My ETH Notification", // Notification name
    "delivery_location": "user@example.com", // Recipient address (e.g., email address or Telegram ID)
    "event_details": {                     // Details about the event
        "network": "ETH_MAINNET",
        "event_type": "ADDRESS_ACTIVITY",
        "addresses": ["0x123...abc"],
        "filters": [
            { 
                "field_name": "value", 
                "operator": "gt", 
                "value": "0.1", 
                "value_type": "int" 
            }
            // ... more filters if applicable
        ],
    }
  },
  // ... other notifications for the user
]
```


# Delete a notification

This endpoint allows you to remove an existing notification.

### Endpoint:

```http
DELETE /api/v1/nodefy/notifications/{notification_id}/
```

### Headers:

```json
Authorization: Bearer YOUR_API_KEY
```

### Requirements:

* `notification_id` (integer): The unique identifier of the notification you want to delete.&#x20;
* You can find the notification ID from the response of the "Create Notification" endpoint or by listing notifications for a specific user ID.

### Response (Success):

```http
204 No Content 
```

### Important Considerations:

* Deleting a webhook is irreversible, so ensure you have the correct `notification_id` before proceeding.
* This endpoint does not require a request body.


# Defining Event Types

Explore the types of events you can monitor through the Nodefy API.

### Overview

Nodefy supports a wide array of onchain events across multiple blockchains:

* **Address Activity:** Track any ERC-20, ERC-721, ERC-1155 transaction or transfer involving a specified address.
* **NFT Activity:** Monitor events like NFT transfers, sales, and minting.
* **GraphQL Events:** Monitor specific smart contract events.
* **Farcaster Casts:** Stay updated on new casts (posts) by specific Farcaster users.

Event types require at least one parameter to successfully define an event for your notification. Reference the table below for required parameters by `event_type`.&#x20;

To build more targeted and effective notifications, we recommend applying additional filters to the event\_type. More detail can be found in the [Using Filters](/our-api-guide/using-filters) section. &#x20;

### Event Types

<table><thead><tr><th width="238">Event_Type</th><th width="272">Description</th><th>Required Parameters</th></tr></thead><tbody><tr><td><code>ADDRESS_ACTIVITY</code></td><td>Monitor any activity (transactions, transfers, etc.) on a specific address</td><td><code>addresses</code> (array of addresses)</td></tr><tr><td><code>GRAPHQL</code></td><td>Monitor specific smart contract events using GraphQL </td><td><code>addresses</code> (smart contract event address)</td></tr><tr><td><code>NFT_ACTIVITY</code></td><td>Monitor NFT-related events (transfers, sales, etc.) for a specific contract or collection</td><td><code>contract_address</code></td></tr><tr><td><code>FARCASTER_CAST</code></td><td>Monitor new casts (posts) on Farcaster</td><td><code>keyword</code>, <code>author_fids</code>, <code>channel</code>, or <code>mentioned_fids</code></td></tr><tr><td>(Other types to come)</td><td>...</td><td>...</td></tr></tbody></table>


# Wallets

Learn how to track any transaction involving a specific wallet address

Notifications on wallet addresses are `address_activity` event type. Common use cases are to provide user payment confirmations, hosted wallet updates or track other smart money wallets. &#x20;

**Event Type:** `address_activity`

To create an address activity event, send a `POST` request to the `/api/v1/nodefy/notifications/` endpoint with the following JSON payload:

#### Example Request:

```json
{
    "external_user_id": "test123",                          //optional
    "channel": "EMAIL",                                     //required
    "notification_name": "Payroll Complete",                //optional
    "template": "Your monthly payroll has been completed"   //optional 
    "delivery_location": "hr@company.xyz",                  //required
    "event_details": {
        "network": "BASE_MAINNET",                          //required 
        "event_type": "ADDRESS_ACTIVITY",                   //required
        "addresses": ["0x60e4d8...a7c6"],                   //required
}
```

#### Required `address_activity` parameter:

* **`addresses`:** An array of wallet address(s) to track. This address(s) should be a high-level identifier for the events you're interested in listening for.&#x20;

#### Wallet Filters

You can easily layer more nuanced filters like `to_address`, `from_address`, `token_type` and more using our filter system. See [Using Filters ](/our-api-guide/using-filters)section for more details. &#x20;


# Smart Contracts

Learn how to monitor specific events or activities happening within a smart contract

Notifications for smart contract interactions use the `graphql` event type. This event type can be used to monitor token swaps, contract deployments, deposits into a lending protocol, votes cast in a DAO, and more. \
\
With event- and topic-level parameters, you have the functionality at your finger tips to build notifications on nuanced, smart contract interactions.&#x20;

**Event Type:** `graphql`

To create a GraphQL event type, send a `POST` request to the `/api/v1/nodefy/notifications/` endpoint with the following JSON payload:

#### Example Request:

```json
{
    "external_user_id": "user123",
    "channel": "EMAIL",
    "notification_name": "Your Mint from Factory Contract",
    "delivery_location": "creator@art.com",
    "event_details": {
        "network": "BASE_MAINNET",
        "event_type": "GRAPHQL",
        "addresses": ["0x60a2...a7c6"],
        "graphql": {
            "topic_2": "0x2a29fb...9a888"
        }
    }
}
```

#### Required `graphql` Parameter:

* `addresses`: An array containing the smart contract address(es) to monitor. This address identifies the contract from which you want to receive event notifications.

#### Optional `graphql` Parameters:

* **`graphql` Object:**  An object to further specify the event using GraphQL query parameters:
  * **`topic_0`:** The event signature (topic0) to filter for specific events.
  * **`topic_1`, `topic_2`, `topic_3`:** Additional indexed topics to further filter events.

#### GraphQL Event Filters

You can apply more specific filters on GraphQL events using our filter system. Filters allow you to capture events based on transaction parameters such as the `fromAddress`, `toAddress`, and `value`. Refer to the ["Using Filters"](/our-api-guide/using-filters) section for more information.


# NFTs

Documentation coming soon


# Farcaster

Learn how to monitor specific cast activity on the Farcaster protocol

Monitor new casts on the Farcaster protocol, filtering by author, mentions, or keywords. This event type can be used to track specific users, identify trending topics, or even build a new Farcaster client.

**Event Type:** `FARCASTER_CAST`

To create a Farcaster event type, send a `POST` request to the `/api/v1/nodefy/notifications/` endpoint with the following JSON payload:

#### Example Request:

```json
{
  "external_user_id": "user123",                           
  "channel": "WEBHOOK",                                    
  "notification_name": "New Farcaster Cast",             
  "delivery_location": "https://webhook.site/cdcf-6718df-asdf",
  "event_details": {
        "network": "FARCASTER",
        "event_type": "FARCASTER_CAST",
        "text": ["keyword1"]
  }
}
```

#### Required `FARCASTER_CAST` Parameters:

*One* of the following parameters must be provided in order to successfully create a webhook to monitor all casts:

* **`text`:** A string containing keywords. The webhook will trigger if any of these keywords are found in a cast.
* **`author_fids`:** An array of Farcaster user IDs (FIDs) to monitor. The webhook will trigger for new casts created by these users.
* **`mentioned_fids`:** An array of FIDs that, if mentioned in a cast, will trigger the webhook.
* **`channel`:** A string of the Farcaster channel name. The webhook will trigger for new casts in this channel(s).

#### Farcaster Event Filters

You can apply more specific filters on Farcaster events using our filter system. Filters allow you to capture events based on parameters such as a range of FIDs, power badge status, and more. Refer to the ["Using Filters"](/our-api-guide/using-filters) section for more information.

#### Example Webhook Payload:

```json
{
  "createdAt": "2024-06-13T18:39:18.083001",
  "data": {
    "notification_name": "Farcaster Payload Test",
    "transaction_hash": "0x81f2a83527061c536d03c9c9be97b28059c7eced",
    "from_wallet": [
      "0xdd7a372377fc633f74ab6e20963803d52f448830"
    ],
    "to_wallet": "Undefined",
    "status": "",
    "asset": "Undefined",
    "value": "This is the cast text that contains a keyword you filtered on",
    "type": "FARCASTER_CAST",
    "network": "FARCASTER",
    "hook_payload": {
      "object": "cast",
      "hash": "0x81f2a83527061c536d03c9c9be97b28059c7eced",
      "thread_hash": "0x81f2a83527061c536d03c9c9be97b28059c7eced",
      "parent_hash": null,
      "parent_url": null,
      "root_parent_url": null,
      "parent_author": {
        "fid": null
      },
      "author": {
        "object": "user",
        "fid": 20698,
        "custody_address": "0x64cc8f7ff6d27151a4deb00674419c7453ca9775",
        "username": "baznocap",
        "display_name": "RJ ⚡️🎩🔵↑",
        "pfp_url": "https://i.imgur.com/dZEGWaA.jpg",
        "profile": {
          "bio": {
            "text": "Building Nodefy.xyz to improve onchain visibility"
          }
        },
        "follower_count": 342,
        "following_count": 285,
        "verifications": [
          "0xdd7a372377fc633f74ab6e20963803d52f448830"
        ],
        "verified_addresses": {
          "eth_addresses": [
            "0xdd7a372377fc633f74ab6e20963803d52f448830"
          ],
          "sol_addresses": []
        },
        "active_status": "inactive",
        "power_badge": false
      },
      "text": "This is the cast text that contains a keyword you filtered on",
      "timestamp": "2024-06-13T18:39:06.000Z",
      "embeds": [],
      "reactions": {
        "likes_count": 0,
        "recasts_count": 0,
        "likes": [],
        "recasts": []
      },
      "replies": {
        "count": 0
      },
      "mentioned_profiles": []
    },
    "author": "baznocap"
  }
}
```


# Using Filters

Learn how to use filters to get notifications on the activity you care about.

Filters are a set of conditions and values that allow you to specify the onchain event that should trigger a notification. You can quickly set parameters on any field in the payload. Filters are created using `field_name`, `operator`, `value_type`, and `value`.

<table><thead><tr><th width="177">Name</th><th>Definition</th></tr></thead><tbody><tr><td><code>field_name</code></td><td>The specific attribute within the event data that you want to filter on. See a complete <a href="#list-of-variables">list of filters</a> below.</td></tr><tr><td><code>operator</code></td><td>Specifies the logical or comparison operation to apply between the <code>field_name</code> and <code>value</code>. See complete<a href="#list-of-operators"> list of operators</a> below.</td></tr><tr><td><code>value_type</code></td><td>The data type of the value you are filtering with</td></tr><tr><td><code>value</code></td><td>The actual value or list of values to compare against the specified <code>operator</code></td></tr></tbody></table>

#### Example Request:

```json
 "filters": [
            { "field_name": str, "operator": str, "value": str, "value_type": str },
            # ... more filters if needed
        ],
```

### List of Operators

Operators must be used with a valid value type to successfully create the notification.

<table><thead><tr><th width="186">Operator</th><th width="403">Definition</th><th>Value_Type</th></tr></thead><tbody><tr><td><code>eq</code></td><td>variable is equal to a value [ = ]</td><td>int, float, str, boolean</td></tr><tr><td><code>neq</code></td><td>variable does not equal a value [ != ]</td><td>int, float, str, boolean</td></tr><tr><td><code>gt</code></td><td>variable is greater than a value [ > ]</td><td>int, float</td></tr><tr><td><code>lt</code></td><td>variable is less than a value [ &#x3C; ]</td><td>int, float</td></tr><tr><td><code>in</code></td><td>variable is in a list </td><td>list</td></tr><tr><td><code>nin</code></td><td>variable is <em>not</em> in a list</td><td>list</td></tr><tr><td><code>contains</code></td><td>a list contains the variable</td><td>string</td></tr><tr><td><code>ncontains</code></td><td>a list does <em>not</em> contain the variable</td><td>string</td></tr></tbody></table>

### List of Variables

You can apply filters on any of the data fields in the primary payload. Please reference the tables below for list of `field_names` and corresponding `value_type`.

#### Address\_Activity Filters

<table><thead><tr><th width="228">Field Name</th><th width="405">Definition</th><th>Value Type</th></tr></thead><tbody><tr><td><code>hash</code></td><td>The unique hash identifying the transaction on the blockchain.</td><td><code>str</code></td></tr><tr><td><code>fromAddress</code></td><td>The address sending the asset in a transaction.</td><td><code>str</code></td></tr><tr><td><code>toAddress</code></td><td>The address receiving the asset in a transaction.</td><td><code>str</code></td></tr><tr><td><code>asset</code></td><td>The symbol or address of the asset or token involved in the transaction. (e.g. <code>ETH</code>, <code>USDC</code>)</td><td><code>str</code></td></tr><tr><td><code>value</code></td><td>The amount of the asset or token transferred or exchanged in the transaction.</td><td><code>int</code> </td></tr><tr><td><code>blockNum</code></td><td>The block number in which the transaction was included.</td><td><code>int</code></td></tr><tr><td><code>category</code></td><td>The category of the transaction (e.g., "external", "internal").</td><td><code>str</code></td></tr></tbody></table>

#### GraphQL Filters

<table><thead><tr><th width="292">Field Name</th><th width="332">Definition</th><th>Value Type</th></tr></thead><tbody><tr><td><code>transaction.hash</code></td><td>The hash of the transaction.</td><td><code>str</code></td></tr><tr><td><code>transaction.from.address</code></td><td>The sender address of the transaction.</td><td><code>str</code></td></tr><tr><td><code>transaction.to.address</code></td><td>The recipient address of the transaction</td><td><code>str</code></td></tr><tr><td><code>transaction.value</code></td><td>The value of the transaction</td><td><code>int</code></td></tr></tbody></table>

Note: additional filters on event address and topic-level parameters can be applied in the GRAPHQL object. See [Smart Contracts ](/our-api-guide/defining-event-types/smart-contracts)for more detail.

#### NFT\_Activity Filters

<table><thead><tr><th width="248">Field Name</th><th width="401">Definition</th><th>Value Type</th></tr></thead><tbody><tr><td><code>hash</code></td><td>The unique hash identifying the transaction on the blockchain.</td><td><code>str</code></td></tr><tr><td><code>fromAddress</code></td><td>The address sending the NFT in a transfer or sale.</td><td><code>str</code></td></tr><tr><td><code>toAddress</code></td><td>The address receiving the NFT in a transfer or sale.</td><td><code>str</code></td></tr><tr><td><code>asset</code></td><td>The address of the NFT contract.</td><td><code>str</code></td></tr><tr><td><code>erc721TokenId</code></td><td>The unique identifier (token ID) of the NFT involved in the event.</td><td><code>int</code></td></tr><tr><td><code>log.logIndex</code></td><td>The index of the log within the block.</td><td><code>int</code></td></tr><tr><td><code>log.blockHash</code></td><td>The hash of the block in which the transaction occurred.</td><td><code>str</code></td></tr><tr><td><code>log.transactionIndex</code></td><td>The index of the transaction within the block.</td><td><code>int</code></td></tr><tr><td><code>log.blockNumber</code></td><td>The block number in which the transaction was included.</td><td><code>int</code></td></tr><tr><td><code>log.data</code></td><td>The raw data associated with the event log.</td><td><code>str</code></td></tr><tr><td><code>log.topics.text</code></td><td>A text representation of the topics (indexed parameters) of the event log.</td><td><code>str</code></td></tr><tr><td><code>log.topics</code></td><td>The topics (indexed parameters) of the event log.</td><td><code>list</code></td></tr><tr><td><code>log.address</code></td><td>The address of the contract that emitted the event.</td><td><code>str</code></td></tr></tbody></table>

#### Farcaster\_Cast Filters:

<table><thead><tr><th width="278">Field Name</th><th width="354">Definition</th><th>Value Type</th></tr></thead><tbody><tr><td><code>hash</code></td><td>The unique hash identifying the cast on Farcaster.</td><td><code>str</code></td></tr><tr><td><code>text</code></td><td>The text content of the cast.</td><td><code>str</code></td></tr><tr><td><code>author.fid</code></td><td>The Farcaster ID (FID) of the author of the cast.</td><td><code>int</code></td></tr><tr><td><code>author.username</code></td><td>The username of the author of the cast.</td><td><code>str</code></td></tr><tr><td><code>author.display.name</code></td><td>The display name of the author of the cast.</td><td><code>str</code></td></tr><tr><td><code>author.pfp.url</code></td><td>The URL of the author's profile picture.</td><td><code>str</code></td></tr><tr><td><code>author.profile.bio.text</code></td><td>The text of the author's profile bio.</td><td><code>str</code></td></tr><tr><td><code>author.follower.count</code></td><td>The number of followers the author has.</td><td><code>int</code></td></tr><tr><td><code>author.following.count</code></td><td>The number of users the author is following.</td><td><code>int</code></td></tr><tr><td><code>power_badge</code></td><td>A boolean of the author's power badge status</td><td><code>boolean</code></td></tr><tr><td><code>timestamp</code></td><td>The timestamp of when the cast was created.</td><td><code>int</code></td></tr><tr><td><code>parent.url</code></td><td>The URL of the farcaster channel</td><td><code>str</code></td></tr><tr><td><code>parent.hash</code></td><td>The hash of the farcaster channel</td><td><code>str</code></td></tr><tr><td><code>thread.hash</code></td><td>The hash of the thread this cast belongs to.</td><td><code>str</code></td></tr><tr><td><code>replies.count</code></td><td>The number of replies to this cast.</td><td><code>int</code></td></tr><tr><td><code>reactions.recasts.text</code></td><td>A text representation of the recast (re-share) reactions to this cast.</td><td><code>str</code></td></tr><tr><td><code>reactions.recasts</code></td><td>An array of recast (re-share) reactions to this cast.</td><td><code>list</code></td></tr><tr><td><code>reactions.likes.text</code></td><td>The like reactions to this cast.</td><td><code>str</code></td></tr><tr><td><code>reactions.likes</code></td><td>An array of like reactions to this cast.</td><td><code>list</code></td></tr></tbody></table>


# Channels

Learn how to build notifications use channels to power cross-platform notification delivery.

Nodefy supports multiple channels for delivering notifications, allowing you to reach your users where they prefer. This section covers instructions on how to set them up and the expected payload structures.

We continue to build out new channels week-to-week, so please do not hesitate to reach out to request a new channel and we will prioritize requests. &#x20;


# Email

Learn how to send email notifications.

### Configuration:

1. **Channel:** Set the `channel` field in your notification payload to `"EMAIL"`.
2. **Delivery Location:** Specify the email address where you want the notification sent in the `delivery_location` field.

#### Example Payload:

```json
{
  "channel": "EMAIL",
  "delivery_location": "user@example.com"
}
```

### Notification Formats:

The email sent to the user will include:

* **Subject:** This can be customized using the `notification_name` field in the request payload or a default template.
* **Body:** The content of the notification, which can be customized using the `template` field in the request payload or a default template. This can include dynamic variables from the event data (e.g., transaction amount, token type).

### Default Template:

**Subject**: New {{`network`}} Activity

**Message**:&#x20;

* From {{`fromAddress`}} to {{`toAddress`}}
* Token: {{`asset`}}
* Value: {{`value`}}
* Transaction Hash: {{`hash`}}

**Default Example:**

<figure><img src="https://1936782662-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FflAA0xqEHKNJ7R9sTrSt%2Fuploads%2FbN6Ywu8b186KONsFA71O%2Fimage.png?alt=media&amp;token=b93df36f-2af6-4c01-a738-867b954c8a15" alt=""><figcaption></figcaption></figure>


# Custom Webhook

Learn how to configure your own webhook to receive notifications.

Send notifications as POST requests to a custom webhook endpoint you define. This provides the most flexibility for handling notifications within your own application or integrating with third-party services.

### Configuration:

1. **Channel:** Set the `channel` field to `"WEBHOOK"`.
2. **Delivery Location:** Provide the full URL of your webhook endpoint in the `delivery_location` field.

#### Example Payload:

```json
{
  "channel": "WEBHOOK",
  "delivery_location": "https://your-app.com/webhook-endpoint"
}
```

### Webhook Payloads (Sent by Nodefy):

Nodefy will send a POST request to your webhook endpoint with a JSON payload containing the details of the triggered event.

#### Example address\_activity payload:

```json
{
  "webhookId": "wh_123abc",  // The ID of the triggered webhook
  "external_user_id": "user123",  // The ID of the user to notify
  "createdAt": "2024-01-01T12:00:00Z",
  "type": "ADDRESS_ACTIVITY", 
  "event": {
    "network": "ETH_MAINNET",
    "activity": [
      {
        "hash": "0x987...xyz",
        "fromAddress": "0x678...ghi",
        "toAddress": "0x123...abc", 
        "asset": "ETH",
        "value": "0.5",
        "category": "external",
        "blockNum": "17000000"
      }
    ]
  }
}
```

#### Example graphql payload:

The exact payload structure for GraphQL events will depend on your specific GraphQL query. Here's an example for a simple ERC-20 `Transfer` event query:

```json
{
  "webhookId": "wh_456def",  // The ID of the triggered webhook
  "external_user_id": "user123", 
  "createdAt": "2024-01-02T15:30:00Z",
  "type": "GRAPHQL",
  "event": {
    "data": {
      "block": {
        "logs": [
          {
            "transaction": {
              "hash": "0x...", 
              "from": {
                "address": "0x..."  // Address of the sender
              },
              "to": {
                "address": "0x..." // Address of the receiver
              },
            },
            "topics": ["0xddf252...", "0x...", "0x..."], 
            "data": "0x..."
          }
        ]
      }
    }
  }
}
```


# Slack

Documentation coming soon


# Telegram

Documentation coming soon


# In-App (coming soon)

Documentation coming soon


# User Info

Managing notifications across many users

This section explains how to pass information about your app's users to the Nodefy API. This enables Nodefy to send targeted notifications to the right users and personalize the notification experience.

**Important Note:** We refer to the users of **your** application as **"External Users"** to distinguish them from the users who manage Nodefy accounts (internal users).

**Identifying External Users** (Optional)

If you are building notifications for many users, it is good practice to include a unique identifier for each user in the payload of your API requests. This identifier should be a string that you can use to identify the user (e.g., a user ID or email address). Use the field `external_user_id` for this purpose.