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.phpindex 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', freturn $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.mdxindex 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.mdxindex 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 variablesor secure vaults to manage them.diff --git a/docs/api-reference/integrations/webhook-security.mdx b/docs/api-reference/integrations/webhook-security.mdxindex 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.yamlindex 8aca1563c..1c9c890a7 100644--- a/docs/api-reference/openapi.yaml+++ b/docs/api-reference/openapi.yaml@@ -385,6 +385,15 @@ paths:minimum: 1default: 1description: "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:- Integrationssummary: 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 Makestatus:type: stringenum: [active, inactive]@@ -917,6 +926,11 @@ paths:type: stringformat: uridescription: The URL where submissions will be sent+ provider_url:+ type: string+ format: uri+ nullable: true+ description: Optional Make scenario URL stored with a Make integrationresponses:"200":description: Webhook created successfully@@ -1576,7 +1590,7 @@ components:readOnly: trueintegration_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