Webhooks

Overview#

Webhooks can be used to be automatically notified in real-time of certain form events such as: a form being created, finalised, signed or even a user template being updated.

The webhook system will attempt to POST to the supplied URI up to 3 times before it gives up. The webhook URI must respond with a 200 OK within 5 seconds to successfully respond to the webhook.

info

Webhook implementation may change in the near future, to include more form events and may also implement exponential backoff etc.

Get Webhooks#

Description: To get a list of webhooks, a HTTP GET request is made to the URL with the session token.

Method: GET

URI: /webhooks/

Headers: Authorization: Third party based authorization header

Returns

Field	Type	Description
id	Integer	Unique ID of the webhook
active	Boolean	Returns true if the webhook is active.
events	String[]	Array of events to listen to
uri	String	The URI to post the webhook to
form_id	Integer	A specific form ID for the webhook*

Example

Request

  curl https://app-api.reiformslive.com.au/webhooks \
  --request GET \
  --header "Authorization: Basic YTlkOWIwYItNGY4Yi1hYTQxLTI5NzZmMTcyZmEyMQ=="

Response

  [
    {
      "id": 1,
      "active": true,
      "events": ["form.finalise","form.sign"],
      "uri": "https://webhook.yourdomain.com/endpoint",
      "form_id": null
    }
  ]

Get Single Webhook#

Description: To get a single webhook a HTTP GET request is made to the URL with the session token.

Method: GET

URI: /webhooks/webhook_id

Headers: Authorization: Third party based authorization header

Returns

Field	Type	Description
id	Integer	Unique ID of the webhook
active	Boolean	Returns true if the webhook is active.
events	String[]	Array of events to listen to
uri	String	The URI to post the webhook to
form_id	Integer	A specific form ID for the webhook*

Example

Request

  curl https://app-api.reiformslive.com.au/webhooks/webhook_id \
  --request GET \
  --header "Authorization: Basic YTlkOWIwYItNGY4Yi1hYTQxLTI5NzZmMTcyZmEyMQ=="

Response

  {
    "id": 1,
    "active": true,
    "events": ["form.finalise","form.sign"],
    "uri": "https://webhook.yourdomain.com/endpoint",
    "form_id": null
  }

Creating a Webhook#

Description: To create a webhook, a HTTP POST request is made to the URL and session token.

Method: POST

URI: /webhooks/

URI Parameters:

Required Parameters:

events: Events to listen to.
uri: URI to send the event to.
Parameters
active: Whether the webhook should be active.
form_id: If the event is specific to a form, a form_id must be passed.
user_template_id: If the event is specific to a user_template, a user_template_id must be passed.
Headers: Authorization: Third party based authorization header

Returns

Field	Type	Description
id	Integer	Unique ID of the webhook
active	Boolean	Returns true if the webhook is active.
events	String[]	Array of events to listen to
uri	String	The URI to post the webhook to
form_id	Integer	A specific form ID for the webhook*

Example

Request

  curl http://app-api.reiformslive.com.au/webhooks/ \
  --request POST \
  --header "content-type: application/json" \
  --header "Authorization: Basic YTlkOWIwYItNGY4Yi1hYTQxLTI5NzZmMTcyZmEyMQ==" \
  --data '{
              "active": true,
              "form_id": 1,
              "events": ["form.finalise"],
              "uri": "https://webhook.yourdomain.com/endpoint"
          }'

Response

  {
    "id": 1,
    "active": true,
    "events": ["form.finalise","form.sign"],
    "uri": "https://webhook.yourdomain.com/endpoint",
    "form_id": null
  }

Updating a Webhook#

Description: To update a webhook, a HTTP PUT request is made to the URL with webhook ID and session token.

Method: PUT

URI: /webhooks/webhook_id

Parameters

events: Events to listen to.
uri: URI to send the event to.
active: Whether the webhook should be active.
form_id: If the event is specific to a form, a form_id must be passed.
user_template_id: If the event is specific to a user_template, a user_template_id must be passed.
Headers: Authorization: Third party based authorization header
Returns

Field	Type	Description
id	Integer	Unique ID of the webhook
active	Boolean	Returns true if the webhook is active.
events	String[]	Array of events to listen to
uri	String	The URI to post the webhook to
form_id	Integer	A specific form ID for the webhook*

Example

Request

  curl http://app-api.reiformslive.com.au/webhooks/ \
  --request PUT \
  --header "content-type: application/json" \
  --header "Authorization: Basic YTlkOWIwYItNGY4Yi1hYTQxLTI5NzZmMTcyZmEyMQ==" \
  --data '{
              "active": false,
              "form_id": 1,
              "events": ["form.finalise"],
              "uri": "https://webhook.yourdomain.com/endpoint"
          }'

Response

  {
    "id": 1,
    "active": false,
    "events": ["form.finalise"],
    "uri": "https://webhook.yourdomain.com/endpoint",
    "form_id": 1
  }

Deleting a webhook#

Description: To delete a webhook, a HTTP DELETE request is made to the URL with the webhook ID and session token.

Method: DELETE

URI: /webhooks/webhook_id

Headers: Authorization: Third party based authorization header

Returns

Field	Type	Description
Message	String	Message relating to the update.

Example

Request

  curl https://app-api.reiformslive.com.au/webhooks/1 \
  --request DELETE \
  --header "Authorization: Basic YTlkOWIwYItNGY4Yi1hYTQxLTI5NzZmMTcyZmEyMQ=="

Response

  {
    "message": "The webhook was successfully deleted."
  }