Webhooks are a way to receive information on your custom service through simple HTTP posts. Webhooks are based on a We'll call you principle. Each time a webhook action is triggered, we'll call your service with a HTTP POST.

Getting started

Start by creating a new webhook integration within the Code app.

Callback url

The URL that points to your webhook. We've created an easy to start example project you can use as a boilerplate or example.

Verify token

This is a secret we send along with each and every call. It's important because you can use this to verify any call Flow.ai makes

Receiving calls

Whenever a webhook is triggered Flow.ai sends along data in JSON format.

    "type": "action",
    "verifyToken": "b34768df-4768-4768-8cfe-0ac99db46ca9",
    "threadId": "99eb45ed85a0a00cef41f55aa03bea17",
    "channelName": "socket",
    "query": "hi",
    "action": "onboarding",
    "params": {},
    "originator": {
        "actorId": "23249a99-a243-448b-asdf-daddd7bafb6c",
        "userId": "flowai|23249a99-1233-448b-ada1-daasafbafb6c",
        "name": "EN Bot",
        "role": "bot",
        "profile": {
            "description": "Flow.ai",
            "locale": "en",
            "picture": "https://flow.ai/img/brains/flowai.svg"
    "user": {
        "userId": "socket|172cda58-12ss-4cd3-b590-aadw8afad0c7|99ebefsw4455a45ed85a0a00ca03bea17",
        "role": "external",
        "name": "Gijs",
        "profile": {
            "fullName": "Gijs van de Nieuwegiessen",
            "picture": "https://en.gravatar.com/userimage/7047529/b39e32c5d5329bfafb378de8e4b25a3b.png"
    "replyUrl": "http://..."


Whenever you receive a webhook call, Flow.ai expects a 200 response code from your server. With each reply you can send back messages and information.

    "verifyToken": "59a755e5-2581-4307-393f-630ad4983adf",
    "messages": [{
        "fallback": "Hi there",
        "responses": [{
            "type": "text",
            "payload": {
                "text": "Hi there"
            "delay": 0

When your webhook runs on Node.js it's best to use flowai-js-templates to send back reply messages. You can also send back simple JSON data.

Delayed replies

Flow.ai expects a webhook to return a reply within seconds. This can cause problems whenever you need to do a long running process. Imagine a bank doing a money transfer. Sometimes that even takes up to a couple days. For those cases Flow.ai provides a mechanism that allows you to reply with messages at a later point in time.

To do this there is a reply URL being send along with each webhook call. You can use this URL to send an HTTP post back to Flow.ai.

The payload using the reply URL is the same as with replying directly

// Node.js example using request
const opts = {
  method: 'POST',
  uri: replyUrl,
  body: {
  json: true


Further reading

results matching ""

    No results matching ""