Callbacks

Callbacks are a way to get information about events that have occurred. This is a more efficient way to get this information than polling our API and waiting for changes. Polling is a tremendous drain on our resources since 99% or more of calls will not produce any new information. Callbacks are also more efficient for the API consumer too, since there's no need to communicate with our systems at all while waiting for events.

Callbacks are an inversion of the usual procedure for APIs where we provide a publicly accessible endpoint and the consumer sends a request of a pre-specified format, then receives a response in another pre-specified format. In the case of a callback, it is the consumer who provides the endpoint and we who send a request with a pre-specified format.

This request contains information about the event that we are reporting to you. In our case, we don't pay attention to what you send as a response to our callback. Our only concern is transmitting the event information to you via the request body.

Types of callback

There are two basic kinds of callbacks that you can receive when setting up e-signing workflows using Scrive Flow. These are callbacks which are provided by the Scrive Flow system itself, plus regular document callbacks which are provided by the standard Scrive API.

Flow callbacks

Flow callbacks are triggered by events that occur during the execution of an Instance.

Currently, all callback events have "version": 1 but, as with other aspects of the API lifecycle, we may decide to upgrade the format of these callback payloads and provide a time frame for the deprecation of earlier versions.

Completion callbacks

This type of event is sent out when a flow instance runs out of stages to execute, performs its finalization actions, and then moves into the completed state.

A sample of the payload for this kind of callback is shown below:

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

Failure callbacks

This event is very similar in nature to the Completion event above, but it occurs when the instance unrecoverably fails and terminates for that reason, rather than because the workflow completed successfully.

A sample of the payload for this kind of callback is shown below:

{
  "type": "failed",
  "version": 1,
  "event_created": "2021-03-15T13:43:67.4589254893Z",
  "flow_instance_id": "e98d5743-9d1a-4e65-bb77-4e117a5451b1"
}

Cancellation callbacks

The following event occurs when either the author cancels the entire flow via the admin interface.

A sample of the payload for this kind of callback is shown below:

{
  "type": "cancelled",
  "version": 1,
  "event_created": "2021-06-15T09:38:28.8361469582Z",
  "flow_instance_id": "21dd7deb-3483-4fdd-bff9-05843a63df57"
}

Rejection callbacks

The following event occurs when a participant either rejects the entire flow (via the overview page) or rejects an individual document within the workflow (causing all other documents in the instance to automatically be canceled and the entire flow to be rejected).

A sample of the payload for this kind of callback is shown below:

{
  "type": "flow_rejected",
  "version": 1,
  "event_created": "2021-04-05T10:23:59.5784451354Z",
  "flow_instance_id": "08b9e7d4-d424-4e66-baa4-06ab6635aad6",
  "message": "Sorry, I don't want to sign this",
  "user_name": "user1",
  "document_name": "doc3"
}

Attempted authentication callbacks

When authentication is required for a participant, we send out this kind of callback when the authentication concludes (whether with a successful result or otherwise).

A sample of the payload for this kind of callback is shown below:

{
  "type": "authentication_attempted",
  "result": "success",
  "version": 1,
  "provider": "sms_otp",
  "user_name": "user1",
  "event_created": "2021-04-12T15:47:06.537487773Z",
  "flow_instance_id": "49235955-29fd-4411-81c3-3222f5c9df30",
  "eid_transaction_id": "9268dcea-24c7-49e5-874b-49da4ed77b16"
}

Maximum failed authentications callbacks

We send out this callback when authentication is required for a participant and the participant has exceeded the limit of failed authentication attempts.

A sample of the payload for this kind of callback is shown below:

{
  "type": "authentication_max_failures_exceeded",
  "version": 1,
  "user_name": "user1",
  "event_created": "2021-04-12T15:47:06.537487773Z",
  "flow_instance_id": "49235955-29fd-4411-81c3-3222f5c9df30"
}

Timeout callbacks

This callback is sent when an in-progress instance becomes timed-out.

A sample of the payload for this kind of callback is shown below:

{
  "type": "timed_out",
  "version": 1,
  "event_created": "2021-04-05T10:23:59.5784451354Z",
  "flow_instance_id": "08b9e7d4-d424-4e66-baa4-06ab6635aad6",
}

Custom callbacks

You can define your own custom callbacks in the process DSL using the callback action. We send out a callback when Flow enters a stage containing such an action.

A sample of the payload for this kind of callback is shown below:

{
  "type": "custom",
  "version": 1,
  "callback_name": "my-callback",
  "event_created": "2021-04-12T15:47:06.537487773Z",
  "flow_instance_id": "49235955-29fd-4411-81c3-3222f5c9df30"
}

Regular Scrive API document callbacks

Further documentation about these kinds of callbacks can be founds at the Callbacks section of the main Scrive API Documentation. To avoid duplicated effort in maintaining the documentation, we will direct you there for a more complete treatment of the subject.

We will list a brief overview of what document-level callbacks we provide here though so that you can decide whether to pursue it.

Document state change callbacks

Currently, all of the callbacks that the main Scrive API provide relate to document status. We guarantee to sent "out at least one" callback (if callbacks are configured for that document) whenever a state change occurs.

The new state will be included in the callback body and will be one of the following:

• pending
• closed
• canceled
• timedout
• rejected

Document callbacks must be configured on a per-document basis and can only be configured via the API (as opposed to the online web app GUI).

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.

• Callbacks
• Webhook
• Polling