Tutorial: Build a Custom Block

In this tutorial you will build a Notify Team block. It posts a message to a chat webhook (Slack, Discord, or any service that accepts a JSON message), and you'll be able to drop it into any route.

New to custom blocks? Read the overview first. It takes two minutes.

Before you start, you need:

• A project.
• An App Config entry holding your webhook URL, for example one named TEAM_WEBHOOK. Keeping the URL there means the secret never sits inside a canvas.

1. Create the block

1. Open your project and go to Custom Blocks.

2. Press New block.

3. Basics. Fill in:

   • Label: Notify Team
   • Identifier: notify_team (filled in for you from the label)
   • Description: Post a message to the team chat

4. Icon. Pick any icon you like.

5. Inputs. Press Add parameter twice:

   Identifier	Label	Type
   webhook_key	Webhook	App Config selector
   prefix	Message prefix	Text input

   Add a hint such as "App Config key that holds the webhook URL" so the person using the block knows what to pick.

6. Review, then press Create block.

2. Build what's inside

Open the new block from the Custom Blocks list. You'll see a canvas with an Entrypoint block.

1. Add a JS Runner block and connect the Entrypoint to it.

2. Paste this code:

   const url = getConfig(params.webhook_key);
   const text = `${params.prefix} ${input.message}`;
   
   await httpClient.post(url, { text });
   
   return { sent: true, text };

   Here params.webhook_key and params.prefix are the two settings you just defined, and input.message is whatever the previous block hands in.

3. Save the canvas.

Whatever the last block returns is the block's output. Here that's { sent: true, text }.

3. Use it in a route

1. Open any route's canvas.
2. Open the block picker and find Notify Team.
3. Drop it in after a block that produces an object with a message field, for example a JS Runner that returns { message: "New signup!" }.
4. Click the block, open the Parameters tab, and fill it in:
   • Webhook: pick TEAM_WEBHOOK.
   • Message prefix: 🚀
5. Save the route and call it.

Your team chat now gets 🚀 New signup!.

4. Choose how it runs

On the block's General tab, set the Execution Mode:

• Leave it on Synchronous if the next block needs { sent, text }, or if the route should fail when the message can't be sent.
• Pick Asynchronous if the caller shouldn't wait for the chat service. That's usually right for a notification.
• Pick Queued if the notification must not be lost, even if the server restarts. It may be sent twice, so it's best for messages where a repeat doesn't matter.

5. Improve it later

Say you want the message to include an emoji picker. Open Custom Blocks, edit Notify Team, and add a Dropdown parameter. Then read it in the JS Runner as params.your_identifier. Every route that uses the block picks up the change, and you don't have to touch any of them.

Where next

• Custom Blocks overview: every parameter type and execution mode.
• JS Runner: everything you can use inside a block's code.
• Scripting context: getConfig, httpClient, logger and more.