Skip to content

Beautiful Open-Source Form Builder

Document Make integration API contract (#1227)

Julien Nahum763d01bf3b84
diff --git a/api/tests/Feature/Integrations/MakeIntegrationTest.php b/api/tests/Feature/Integrations/MakeIntegrationTest.php
index 9d5232cf3..8e197c0be 100644
--- a/api/tests/Feature/Integrations/MakeIntegrationTest.php
+++ b/api/tests/Feature/Integrations/MakeIntegrationTest.php
@@ -11,6 +11,7 @@ test('make integration fires webhook on form submission with correct payload', f
$user = $this->actingAsProUser();
$workspace = $this->createUserWorkspace($user);
$form = $this->createForm($user, $workspace, [
+ 'editable_submissions' => true,
'properties' => [
[
'id' => 'name',
@@ -41,8 +42,12 @@ test('make integration fires webhook on form submission with correct payload', f
return $request->url() === 'https://example.com/make-hook/test123'
&& $payload['form_id'] === $form->id
- && isset($payload['data'])
- && isset($payload['form_title'])
+ && $payload['form_title'] === $form->title
+ && $payload['form_slug'] === $form->slug
+ && is_int($payload['submission_id'])
+ && isset($payload['edit_link'])
+ && $payload['data']['name']['name'] === 'Name'
+ && $payload['data']['name']['type'] === 'text'
&& !isset($payload['submission'])
&& !isset($payload['message']);
});
diff --git a/docs/api-reference/forms/list-workspace-forms.mdx b/docs/api-reference/forms/list-workspace-forms.mdx
index 4fe265c1d..ad4cca60f 100644
--- a/docs/api-reference/forms/list-workspace-forms.mdx
+++ b/docs/api-reference/forms/list-workspace-forms.mdx
@@ -32,9 +32,10 @@ Authorization: Bearer <token>
### Query Parameters
-| Parameter | Type | Description | Default |
-|-----------|--------|------------------------------------------------|---------|
-| page | number | Page number for pagination. | 1 |
+| Parameter | Type | Description | Default |
+|-----------|--------|--------------------------------------------------|---------|
+| page | number | Page number for pagination. | 1 |
+| per_page | number | Number of forms per page (minimum 1, maximum 100). | 10 |
## Response
@@ -78,4 +79,3 @@ To get the full form including fields (`properties`), call the [Get Form](./get-
`403 Forbidden` – The token does not include the required `forms-read` ability, or you do not have access to the workspace.
`404 Not Found` – The workspace does not exist.
-
diff --git a/docs/api-reference/integrations/create-webhook-integration.mdx b/docs/api-reference/integrations/create-webhook-integration.mdx
index a5c98c42c..44676095e 100644
--- a/docs/api-reference/integrations/create-webhook-integration.mdx
+++ b/docs/api-reference/integrations/create-webhook-integration.mdx
@@ -17,7 +17,9 @@ This endpoint requires a **Personal Access Token** with the `manage-integrations
</ParamField>
<ParamField body="integration_id" type="string" required>
- Must be set to `"webhook"` for webhook integrations.
+ Use `"webhook"` for a generic webhook integration or `"make"` for the
+ official OpnForm app on Make. Both values are registered integration
+ handlers exposed by this endpoint.
</ParamField>
<ParamField body="status" type="string" required>
@@ -53,6 +55,11 @@ Example:
}
```
+</ParamField>
+
+<ParamField body="provider_url" type="string">
+Optional Make scenario URL. This property is accepted by the `"make"`
+integration and is ignored by generic webhook integrations.
</ParamField>
</Expandable>
</ParamField>
@@ -82,6 +89,25 @@ curl -X POST 'https://api.opnform.com/open/forms/123/integrations' \
```
</RequestExample>
+For the official OpnForm app on Make, the attach request uses the same endpoint
+with the provider-specific integration identifier:
+
+<RequestExample>
+```bash cURL Make
+curl -X POST 'https://api.opnform.com/open/forms/123/integrations' \
+ -H 'Authorization: Bearer YOUR_PAT' \
+ -H 'Content-Type: application/json' \
+ -d '{
+ "integration_id": "make",
+ "status": "active",
+ "logic": null,
+ "data": {
+ "webhook_url": "https://hook.eu1.make.com/example"
+ }
+ }'
+```
+</RequestExample>
+
## Response
`200 OK` – Webhook created successfully.
@@ -156,6 +182,32 @@ For security reasons, the following headers cannot be customized:
See [Validating Webhook Signatures](/api-reference/integrations/webhook-security) for implementation examples.
+## Make payload
+
+The `"make"` handler sends a provider-specific payload matching the output
+interface of the OpnForm Make app:
+
+```json
+{
+ "form_id": 123,
+ "form_title": "Contact Form",
+ "form_slug": "contact-form",
+ "submission_id": 456,
+ "edit_link": "https://opnform.com/forms/contact-form?submission_id=example",
+ "data": {
+ "field-id": {
+ "value": "Jane Doe",
+ "name": "Name",
+ "type": "text"
+ }
+ }
+}
+```
+
+`edit_link` is present only when editable submissions are enabled. Unlike the
+generic webhook payload, the Make payload omits the deprecated `submission` and
+`message` properties.
+
<Warning>
Do not commit webhook secrets to version control. Use environment variables
or secure vaults to manage them.
diff --git a/docs/api-reference/integrations/webhook-security.mdx b/docs/api-reference/integrations/webhook-security.mdx
index 75261d12d..1774a1907 100644
--- a/docs/api-reference/integrations/webhook-security.mdx
+++ b/docs/api-reference/integrations/webhook-security.mdx
@@ -191,11 +191,26 @@ X-Custom-Header: custom-value
{
"form_id": 123,
"form_title": "Contact Form",
+ "form_slug": "contact-form",
"submission_id": 456,
- "submission": { ... }
+ "edit_link": "https://opnform.com/forms/contact-form?submission_id=example",
+ "submission": { "Name": "Jane Doe" },
+ "data": {
+ "field-id": {
+ "value": "Jane Doe",
+ "name": "Name",
+ "type": "text"
+ }
+ }
}
```
+The generic `"webhook"` integration keeps the legacy `submission` property for
+backward compatibility. Provider-specific integrations such as `"make"` expose
+the same `form_id`, `form_title`, `form_slug`, `submission_id`, optional
+`edit_link`, and `data` properties while omitting the deprecated `submission`
+and `message` properties.
+
## Security Best Practices
<Tip>
diff --git a/docs/api-reference/openapi.yaml b/docs/api-reference/openapi.yaml
index 8aca1563c..1c9c890a7 100644
--- a/docs/api-reference/openapi.yaml
+++ b/docs/api-reference/openapi.yaml
@@ -385,6 +385,15 @@ paths:
minimum: 1
default: 1
description: "Pagination page number"
+ - name: per_page
+ in: query
+ required: false
+ schema:
+ type: number
+ minimum: 1
+ maximum: 100
+ default: 10
+ description: "Number of forms per page"
responses:
"200":
description: Successful
@@ -879,7 +888,7 @@ paths:
tags:
- Integrations
summary: Create Webhook Integration
- description: "Create a new webhook integration for a form. Requires `manage-integrations` ability."
+ description: "Create a new generic webhook or provider-specific Make integration for a form. Requires `manage-integrations` ability."
security:
- bearerAuth: []
parameters:
@@ -901,8 +910,8 @@ paths:
properties:
integration_id:
type: string
- enum: [webhook]
- description: Must be "webhook"
+ enum: [webhook, make]
+ description: Use "webhook" for a generic webhook or "make" for the official OpnForm app on Make
status:
type: string
enum: [active, inactive]
@@ -917,6 +926,11 @@ paths:
type: string
format: uri
description: The URL where submissions will be sent
+ provider_url:
+ type: string
+ format: uri
+ nullable: true
+ description: Optional Make scenario URL stored with a Make integration
responses:
"200":
description: Webhook created successfully
@@ -1576,7 +1590,7 @@ components:
readOnly: true
integration_id:
type: string
- description: Type of integration (currently only "webhook" is exposed via API).
+ description: Type of integration exposed via API, including "webhook" and the provider-specific "make" integration.
example: "webhook"
status:
type: string