Event-Driven Webhooks for Dynamic Responses

Setting Up Your Webhook with DreamNet 🚀

This video will guide you through the entire process of getting your webhook up and running. We'll cover how to clone and run our example server, expose it to the internet using ngrok, and finally, how to register your extension in the DreamNet Developer Portal to get your credentials and test the live connection.

What are Webhooks?

Webhooks are the primary tool we provide for you to extend the DreamNet platform. They allow you to listen to conversations in real-time and, optionally, modify the characters' responses.

• What are they? Automated notifications that our platform sends to your own server whenever an event occurs in a conversation (e.g., when a user sends a message).

• Why use them? They are your gateway to:

  • Read data: Analyze conversations, log events, or trigger external logic.

  • Transform responses: Modify, filter, or completely replace what a character is about to say before the user sees it.

Quick Start Guide: Your Webhook Server

Follow these steps to set up an example server that receives and responds to our webhooks.

Clone the Example Repository

First, get the example server code on your local machine.

# Clone the repository
git clone https://github.com/Doodles/webhook-example.git

# Navigate into the new directory
cd webhook-example

Prerequisites

Note on Technology Stack: The following prerequisites are for our example boilerplate. If you choose not to use it, you are free to use any technology stack you prefer, as long as it is compatible with the Swig SDKs (currently TypeScript and Rust).

You will need the following installed in your development environment:

• Node.js (v20 or higher)

• npm

• Typescript

Environment Setup

Your server needs a secret key to function.Create a file named .env in the project's root directory and add the following variable:

# This is your secret key. You can make up whatever you want.
# Make sure it's secure and save it!
WEBHOOK_SECRET=your_webhook_secret_here

This key is essential for verifying that requests received by your server are legitimately from our platform.

Start the Example Server

Now you can install the dependencies and start the server.

# Install dependencies
npm install

# Start the server in development mode
npm run dev

Once started, you'll see a message in your terminal indicating that the server is running, usually at http://localhost:4000.

Note: This command runs your server locally. For our platform to send events to it, your server must be accessible from the internet. See the Testing with a Public Endpoint using ngrok section below for instructions on how to do this.

Explore the Source Code

The example server is the best way to understand how everything works. We highly encourage you to explore the source code in the official GitHub repository to see the signature verification and dynamic response logic in action.

Visit the Webhook Example Repository

Understanding Our Webhook Implementation

The Endpoint

Your server must have an endpoint that accepts POST requests at the root path (/). Our platform will send all events to this URL.

Signature Verification

Every request we send will include an HTTP header called x-signature. This is an HMAC SHA-256 signature generated using the request body and your WEBHOOK_SECRET. You must verify this signature on every request. This ensures the data is authentic and has not been tampered with. The example server we provide already includes a verifySignature function that does this for you. If the signature is invalid, the server should respond with a 403 Forbidden error.

Responding to Events

Once you have verified the signature, your server can process the event. The request body (req.body) will contain the event data, including the eventType.

• To simply 'read' the event: If you only want to log the data or trigger an external action without changing the character's response, simply respond with a 200 status code.

• To 'transform' the response: If you want to modify what the character is going to say, your server must respond with a 200 status code and a JSON body containing the original object, but with a modified text property.

// Example of how to transform a response
return res.status(200).json({
  ...data, // All original event data is included
  text: "This is the new text the character will say."
});

In the example server, if the eventType is "request", one text is returned; otherwise, a different text is returned. You can adapt this logic for your own needs.

Testing Your Webhook

Important: ngrok is intended for local development and testing only. For your final submission, you must deploy your webhook to a public hosting service (e.g., Vercel, Railway, Heroku) and provide that stable URL.

Testing Locally with curl

To test your server, you need to send it a POST request with a valid signature.

Generate a Test Signature: You can generate a signature from your terminal using openssl. Make sure to use the same WEBHOOK_SECRET you have in your .env file.

echo -n '{"eventType":"request"}' | openssl dgst -sha256 -hmac "your_webhook_secret_here" -binary | base64

This command will generate a base64 string. That is your signature.

Send the Test Request: Now, use curl to send the request to your local server. Replace YOUR_GENERATED_SIGNATURE with the signature you obtained.

curl -X POST http://localhost:4000 \
  -H "Content-Type: application/json" \
  -H "x-signature: YOUR_GENERATED_SIGNATURE" \
  -d '{"eventType": "request"}'

Testing with a Public Endpoint using ngrok (Recommended)

To test the full integration with our platform, your server needs to be accessible from the internet via an HTTPS URL. The ngrok tool is perfect for this.

Install and Configure ngrok:

• Visit the ngrok downloads page to install it.

• Sign up for a free account to get your authtoken.

• Configure ngrok with your token:

  ngrok config add-authtoken <your-authtoken>

Expose Your Local Server: To create a secure tunnel to your local server running on port 4000:

ngrok http 4000
```ngrok` will provide you with a public HTTPS URL (e.g., `[https://random-tunnel.ngrok.io](https://random-tunnel.ngrok.io)`). This is the URL you will need to register as your `webhookURL` in the developer portal.

**Live Testing:**
Once you have registered your `ngrok` URL in our portal, simply use our chat interface. Any message you send will trigger an event that will be sent to your local server via `ngrok`, allowing you to debug in real-time.