Webhooks

A webhook is a way to provide other applications with a notification that a form submission has taken place. This allows custom, flexible integrations with your own backend systems or services.

Webhook submission events can be configured on the Workflow tab after selecting a form in the console. 

By default, the notification will simply contain information that identifies the form submission, not the payload itself. This means that the notifications are fast and lightweight, and it gives you full flexibility over what action you want to take when a submission happens.

For example, you may wish to update the status in your backend system, or you may want to take it a step further and request the full submission payload for backend integration or storage.

Types of Webhooks Events

 There are two types of webhook events you may wish to use:

CivicPlus Hosted API

Our hosted API (Application Programming Interface) service allows your developers to simply write code and deploy it without worrying about infrastructure. The APIs are hosted using serverless technology for resiliency and scaling.

If you’re hosting your webhook script through CivicPlus, you can easily access this by selecting the CivicPlus Hosted API. You will be shown a list of APIs, and once you choose one, a list of all available routes for that endpoint.

Custom URL

If you are hosting your own APIs or using a middleware service such as Jitterbit, Mulesoft, or Boomi then you can select the Custom URL webhook. For this submission event, you can simply enter the full URL to your endpoint, and CivicPlus will send the webhook notification to that URL when a submission takes place.

Payload

The payload for webhooks contains information that allows you to identify the submission: 

• formId: The ID number of the form that was submitted
• externalId: An optional custom ID, if you passed one when invoking the form
• submissionId: The ID for the submission
• submissionTimestamp: An ISO_8601 Timestamp at the time of submission

The payload will be passed as JSON data.

Payload Example

{
  "formId": 160,
  "externalId": "external identifier",
  "submissionId": "85fad0a4-b778-4aea-a6e7-671d84d58156",
  "submissionTimestamp": "2019-01-31T09:15:00.000Z"
}

Once your webhook is triggered, if you would like to retrieve your form data this can be done using the OneBlink Software Development Kit (SDK) or the CivicPlus Command Line Interface (CLI).

The current SDK is written in NodeJS and can be used to include in your server-side code to retrieve your submission data (as well as functions like pre-populating a form, for example).

The SDK is hosted on Github and NPM, so it can be easily included in your projects.