Skip to main content

Using custom callbacks

In this article, we'll show you how to use custom callbacks. Custom callbacks are an addition to the basic callbacks Scrive Flow offers so we encourage you to read the guide on setting up the basic callbacks first.

Why use custom callbacks?​

Sometimes the basic Flow callbacks are not sufficient. For example, if you wanted to send out a notification using your own mail system, you would like to know when a process starts. A callback would be useful in this situation but Flow does not provide such a callback at the moment.

Luckily it's possible to specify your own custom callbacks in the process DSL. We'll use the notification example in this guide.

We will be using webhook.site to capture the callbacks from the Scrive system. In a real integration, you'll obviously be pointing the callback at your own systems.

Setting up the process​

We'll define a simple process with one participant, one document and a callback that will be sent out at the beginning of the process.

We specify the custom callback using a callback action. Each callback has a callback-name which can be used to identify the callback in your system. In this example we'll use the name notify-participant.

{
  "dsl-version": "0.2.0",
  "stages": [
    {
      "initial": {
        "actions": [
          {
            "callback": {
              "callback-name": "notify-participant"
            }
          }
        ],
        "expect": {
          "signed-by": {
            "users": ["user1"],
            "documents": ["doc1"]
          }
        }
      }
    }
  ]
}

Starting the instance​

It is at the moment that we create a running instance from the draft that we pass any configuration about where to send callbacks.

Just like we did in the guide on setting up callbacks, we are going to send a JSON object detailing concrete values for the variable names in the process as well as the callback URL and version:

{
  "title": "foobar",
  "process_parameters": {
    "documents": {
      "doc1": "2"
    },
    "users": {
      "user1": {
        "id_type": "user_id",
        "id": "1"
      }
    },
    "messages": {}
  },
  "callback": {
    "url": "https://webhook.site/cbd18804-ba4c-46c5-9942-a1232e4db09e",
    "version": 1
  }
}

It's worth noting that the custom callbacks and the basic ones share the same URL and version configuration. In practice this means they are all sent to the same system. If you need to send the custom callbacks to a different system you will have to forward them yourself.

Receiving the callback​

When you start the draft and go back to webhook.site you should see that their service did indeed receive some information as a callback.

You can see that Scrive's systems sent a POST request containing a JSON object that contains information about the event:

{
  "type": "custom",
  "callback_name": "notify-participant",
  "version": 1,
  "event_created": "2021-03-10T16:40:17.332350921Z",
  "flow_instance_id": "1e3a60ea-80b8-44bb-9e59-c64d8697b959"
}

Within this object, we have the type of event, which in this case indicates a custom event. We also have the callback_name that we specified in the process DSL.

Further metadata provided includes the flow_instance_id which corresponds to the ID of the flow instance that you created when you instantiated the draft.

Further Reading​

If you would like a deeper knowledge of the topics covered here, then the following articles may be useful. You are not required to read them in order to understand the rest of this guide.