Skip to main content

Webhooks

Webhooks let your RedFlare agents reach out to the systems you already use. Whenever something happens during a conversation, a webhook can send the right data to an external service in real time, so your records stay current and your automations keep running without anyone lifting a finger.

Webhooks

Think of a webhook as a reusable connection to an outside API. You set it up once, describe what to send and where, and then your agents can trigger it on demand to exchange data with third-party services. Because a webhook can both send information and read the response back, your agent can look up a booking, create a ticket, check stock, or update a CRM record and then keep talking about the result, all in the same conversation.

What you can do​

  • Connect an agent to any external API and trigger it in real time to exchange data with third-party services.
  • Choose the request method for each connection: GET, POST, PUT, PATCH, or DELETE.
  • Add Headers, Query Params, Path Params, and a Body to shape exactly what gets sent.
  • Mark values as Dynamic, Static, or Secret so sensitive details stay protected and changing values get filled in at runtime.
  • Set a Data type for every value: String, Number, Integer, or Boolean, so the receiving service gets data in the format it expects.
  • Define Dynamic Params that your agent extracts from the conversation, such as a name, date, or ID.
  • Store reusable API & Webhook Secrets like API keys, then reference them across your webhooks.
  • Set a request Timeout so a slow endpoint never holds things up.
  • Link a webhook to one or more tools so an agent knows when and how to call it, and unlink it cleanly when you no longer need it.

How it works​

A webhook on its own is just a saved recipe for an API call. It becomes useful when it's linked to a tool that your agent can use during a conversation. Here's what actually happens behind the scenes:

  1. You describe the call once. RedFlare stores the method, URL, timeout, and every header, query param, path param, and body field, along with how each value should be supplied (Dynamic, Static, or Secret).
  2. The agent decides when to call it. During a live conversation, your agent recognises that it needs to reach the external service, based on the webhook's name and description, and triggers the connection at the right moment.
  3. Dynamic values are filled from the conversation. For anything marked Dynamic, the agent pulls the value out of what the customer just said, like an order number or a date. If a required dynamic value is missing, the call is stopped rather than sent half-formed.
  4. Secrets are fetched safely at the last second. For anything marked Secret, RedFlare looks up the stored credential at the moment of the call and drops it into the request. The real value is never shown in your webhook setup or exposed to the agent.
  5. Values are formatted to match the data type. Each value is converted to the String, Number, Integer, or Boolean type you chose, so the endpoint receives clean, correctly typed data. Path params are slotted into the URL in order to target the exact resource.
  6. The request is sent and timed. RedFlare makes the call and waits only as long as your Timeout allows. If the endpoint takes too long, the call is abandoned so the conversation isn't left hanging.
  7. The response comes back into the conversation. A successful reply is read back to your agent, which can use the returned data to answer the customer. If the endpoint reports an error, the agent is told the call didn't succeed so it can respond gracefully.

Because all the changing details are filled in at the moment of each call, one webhook works for every conversation. You never need a separate copy per customer.

Create a webhook​

When you open Webhooks for the first time you'll see No webhooks created yet with a short note about extending your agent's capabilities. Start from there or from the + action in the header.

  1. Select Create Webhook (or the + button in the top right).
  2. Enter a Name so you can recognise this connection later.
  3. Add a Description explaining what the webhook does and when it should be used. This is more than a label: your agent reads it to decide when to trigger the call, so be clear and specific.
  4. Pick the Method for the request: GET, POST, PUT, PATCH, or DELETE.
  5. Enter the URL of the endpoint you want to call.
  6. Adjust the Timeout slider to set how long RedFlare waits for a response. The default is 10 seconds, and you can extend it for slower endpoints.
  7. Select Create to save your webhook.
note

The Body section only appears for methods that send data (everything except GET), so you'll see it once you choose POST, PUT, PATCH, or DELETE.

Shape the request​

Below the basics, you can fine-tune exactly what each request carries. Every section has an add control so you can build up key-value pairs one at a time.

  • Headers — Set the headers your webhook needs for authentication, formatting, or custom behaviours.
  • Query Params — Key-value pairs appended to the URL to filter results, control pagination, or pass options.
  • Path Params — Variables embedded in the URL structure to target a specific resource, like a User ID or Order Number. These are slotted into the URL in the order you add them.
  • Body — The main data payload, used to send the detailed information the receiving server needs to process the action.
  • Dynamic Params — Variables your agent extracts from the conversation and passes into the request at runtime.

For each header, query param, path param, or body field you can set how its value is supplied:

  1. Add a field, then give it a Name.
  2. Choose a Data type: String, Number, Integer, or Boolean. RedFlare converts the value to this type before sending it.
  3. Choose a Value type:
    • Dynamic — the value is supplied at runtime, extracted by your agent from the conversation.
    • Static — you type a fixed value yourself, and it's sent the same way every time.
    • Secret — you select a stored secret so the real value stays hidden and is only pulled in at the moment of the call.
tip

Name your Dynamic fields the same way you'd describe them to a person, like order_number or customer_email. Clear names make it easier for your agent to match what the customer says to the right field.

Store an API or webhook secret​

Secrets keep your API keys and credentials out of plain sight. Once saved, you can reuse them anywhere a value type is set to Secret. You'll find these under API & Webhook Secrets.

  1. Open API & Webhook Secrets. If nothing is there yet, you'll see No webhooks secrets added yet.
  2. Select the option to add a secret.
  3. Enter a Name for the secret.
  4. Enter the Value you want to keep secure.
  5. Save the secret. It's now available to select wherever a field uses the Secret value type.

When a webhook runs, RedFlare retrieves the secret's real value only at the moment the request is sent. The credential is never stored inside the webhook itself or shown back to you after saving, so your keys stay protected even as you reuse them across many connections.

tip

Give secrets clear, descriptive names like Stripe API Key or CRM Token. When you're building a webhook and pick a Secret value, a well-named list makes it obvious which credential to choose.

Manage and delete webhooks​

Your webhooks appear in a list showing each one's Name, URL, Methods, and Created at date, with an Action menu for each row. Use the search box at the top to filter when the list grows.

Editing a webhook updates the saved connection in place. Any tool already pointing at it picks up your changes automatically, so you rarely need to rebuild a webhook from scratch.

To remove a webhook, open its action menu and choose delete. If the webhook is still connected to tools, RedFlare protects your live setup:

This webhook is currently in use. To prevent breaking active tools, you must unlink it from the connected tools listed below before deleting.

Select Unlink Tool for each connected tool listed, then delete the webhook once nothing depends on it.

note

The guard against deleting a connected webhook exists so an agent never tries to call a connection that's been removed mid-conversation. Unlinking first keeps your active tools working right up until you delete.

Tips​

tip

Use Dynamic Params for anything that changes per conversation, like a caller's name or an order number. Your agent fills these in on the fly, so a single webhook works for every interaction instead of one per customer.

tip

Write the Description as if you're briefing the agent. A precise description ("Look up the status of an existing order by its order number") helps your agent trigger the webhook at exactly the right moment and gather the right details first.

note

Keep your Timeout realistic for the endpoint you're calling. A fast lookup is fine at the 10-second default, but a heavier action may need more headroom. If an endpoint times out, the call is dropped and your agent is told it didn't go through.

note

If you save a new webhook or secret and don't see it immediately, give the list a moment. RedFlare refreshes your webhooks regularly, and you can also re-run the search to confirm everything's in place.