Webhooks

In this guide, we will look at how to register and consume webhooks to integrate your app with Forms Live. With webhooks, your app can know when something happens in Forms Live, such as when a form is finalised, signed, or when a user template is updated.

Registering webhooks

To register a new webhook, you need to have a URL in your app that Forms Live can call. You can configure a new webhook via the API, specifying the events you want to listen for, and providing your URL.

The webhook system will attempt to POST to your supplied URI up to 3 times before giving up. Your webhook URI must respond with a 200 OK status within 5 seconds to successfully acknowledge the webhook.

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

Now, whenever something of interest happens in your app, a webhook is fired off by Forms Live. In the next section, we'll look at how to manage webhooks.

Managing webhooks

Forms Live provides a comprehensive set of endpoints to manage your webhooks:

1. List all webhooks: Retrieve all webhooks configured for your account
2. Get a single webhook: Retrieve details about a specific webhook
3. Create a webhook: Register a new webhook with your desired events and URL
4. Update a webhook: Modify an existing webhook's configuration
5. Delete a webhook: Remove a webhook when it's no longer needed

Event types

{
  "id": "7a8b9c0d1e2f",
  "type": "form.finalise",
  "payload": {
    "id": 123,
    "template_version_id": 456,
    "agency_id": 789,
    "user_id": 101,
    "name": "Property Lease Agreement",
    "template": false,
    "finalised": true,
    "private": false,
    "created": 1506294669,
    "updated": 1506294769,
    "given_name": "John",
    "surname": "Smith",
    "template_cost": 80,
    "template_id": 202,
    "template_name": "Residential Lease Agreement",
    "template_code": "RLA2023",
    "template_instruction_pages": 1
  }
}

Webhook endpoints

List all webhooks

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

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

Get a single webhook

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

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

Create a webhook

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

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

Update a webhook

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

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

Delete a webhook

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

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

Reliability and best practices

When implementing webhooks with Forms Live, consider the following best practices:

1. Quick responses: Your webhook endpoint should respond with a 200 OK status quickly (within 5 seconds) to acknowledge receipt
2. Idempotency: Design your webhook handler to be idempotent, as the same webhook might be delivered multiple times in case of retries
3. Validation: Implement proper request validation to ensure the webhook request is legitimate
4. Async processing: Acknowledge the webhook quickly, then process the data asynchronously if needed
5. Logging: Maintain logs of received webhooks for debugging purposes

By following these best practices, you'll ensure a robust integration with Forms Live's webhook system.