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.

These are form events and, as such, can be configured on the Submission Events 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 simply update a 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

Part of the CivicPlus platform is API hosting. In the spirit of NoOps, our hosted API service allows your developers to simply write code and deploy, without needing to worry about infrastructure. The APIs are hosted using serverless technology for resiliency and scaling.

If you’re hosting your webhook script on the CivicPlus platform, you can easily access this by selecting the CivicPlus Hosted API.

You will be shown a list of APIs, and once you select 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, Boomi, etc., then you can select the Custom URL webhook. 

For this 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 - A 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 SDK or the CivicPlus 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, and so can be easily included in your projects. 

• Note: Pass the form submissionId to the getSubmissionData() function to retrieve the submission data.