Tip of the day

Support tickets can be submitted directly from application

Outbound: Webhooks

Estimated reading: 4 minutes 244 views

Webhook is an API call made from cellosign to to your application, this our method to keep your application on track in regards to business process. Webhooks are very flexible tool and if used correctly it can provide your organization a complete visibility on the whereabouts of your business process.

Webhook types

The table below lists types of webhooks, there are are different types of web hooks that serves different purposes.

Archiverequest at the end of a business process. This web hook can be executed to deliver a business process products that includes at least signed document, form data, attachments etc.
On Field changeGet data from 3rd party application based on changes carried out in form, while user editing it.
Storage callbackPost data to API after a storage call been executed
On SubmittedPost data to API after a client submits a form
On Logged inPost data when client logs in to a form, activated with click on SMS or Email
On loadedPost data when client form is loaded and operational
On ExpiredPost data when transaction is expired
On deletedPost data when transaction is deleted
On createdPost data when transaction is created. This is useful on business process that generates multiple transactions

Setting up Webhook

To configure a webhook, we basically need an Access to the remote end point and configure how it works.  The table below details the configuration options for webhooks.

Follow these steps to add Webhook:

  1. At the dashboard click integrations
  2. locate Webhooks integration pane
  3. click “Add”
FieldWhat it’s for?
AliasA readable name for the web hook. In some cases webhooks can be configured per business process, so provide meaningful name
TypeSelect webhook type
Implicit/ExplicitImplicit means that whenever a business process is completed, this webhook will fire off. Explicit means, don’t fire unless instructed. See below options for setting up explicit.
urlInsert an API end point address
TimeoutSet timeout in seconds on the remote endpoint. If you know that your endpoint process takes time, increase the default
verify sslIn case your address is deployed with https protocol it’s recommended that SSL handshake will be carried out successfully. Otherwise you can turn this off.
HeadersIn case your endpoint required custom headers, click add and enter key/value pairs
AuthenticationIt is recommended to use a mechanism for authenticating requests from Cellosign to your endpoint. For that we have couple of options:
1. Basic authentication. Add user name and password. Cellosign will convert it to base64 according to Basic auth standard
2. Custom authentication. Insert key/value pair for authentication
3. Authenticate with Secret. This is a bearer token mechanism. See Secret documentation for details
Content type, AcceptBy default Cellosign webhooks generates and accept JSON content. You may select these settings to be converted to XML. Note: This is a simple conversion from JSON to XML request body and vice versa, This is not WSDL/Soap operation.
Request body exampleThis section displays how a standard body request data structure looks like, based on the webhook types. Each webhook type displays different body request example.
Response successThis is an example of how the response from your endpoint should respond success.
Response errorThis is an example of how the response from your endpoint should look like in case of an error.
Save/DeleteSave the configuration or delete webhook
TestClick this button will fire the sample above based on the configuration and will return the result to webhook pane.

Explicitly/Implicitly Webhook implementation

A webhook can be setup to fire off Implicitly that means every business processes will fire this integration. For example a webhook for Archive will be posted to your Endpoint when every business process within your project is completed.

This is the recommended approach if indeed all your business process should end up in in this manner. However if there are different use cases, such as: separate endpoints or some business process does not need API calls, it is recommended to couple webhook with a business process Explicitly.

To explicitly couple a webhook with business process we purpose two options:

  1. Manually connect it to specific template(s), which means, templates configuration will include explicit coupling with a webhook. See details for coupling webhook to template in webhook specific page
  2. Ad hoc integration for a business process: When the webhook is set to explicit the webhook pane display the integration code that can be added to create session request. Simply add the code to your request. All ad hoc integration can be add within the integrations Array. Note that the UUID represents  specific webhook

Leave a Comment

Share this Doc

Outbound: Webhooks

Or copy link