> ## Documentation Index
> Fetch the complete documentation index at: https://docs.opnform.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Update Webhook Integration

> Update an existing webhook integration. Requires `manage-integrations` ability.

# Update Webhook Integration

Modify an existing webhook integration's URL, secret, headers, or status.

## Authentication & Scope

This endpoint requires a **Personal Access Token** with the `manage-integrations` ability.

## Request

<ParamField path="form" type="number" required>
  The ID of the form containing the webhook.
</ParamField>

<ParamField path="integrationid" type="number" required>
  The ID of the webhook integration to update.
</ParamField>

<ParamField body="integration_id" type="string" required>
  Must be set to `"webhook"`.
</ParamField>

<ParamField body="status" type="string">
  The status of the webhook. Allowed values: `"active"`, `"inactive"`.
</ParamField>

<ParamField body="data" type="object" required>
  Configuration object containing webhook details. All fields are optional.

  <Expandable title="data properties">
    <ParamField body="webhook_url" type="string">
      The updated URL where form submissions will be sent. Must be a valid HTTPS URL that resolves only to public IP addresses. Private, loopback, link-local, and cloud metadata addresses are rejected.
    </ParamField>

    <ParamField body="webhook_secret" type="string">
      Update the signing secret for HMAC-SHA256 validation. Must be at least 12
      characters. Provide a new value to rotate the secret.
    </ParamField>

    <ParamField body="webhook_headers" type="object">
      Update custom HTTP headers. Replaces all existing headers with the provided ones. Maximum 10 headers allowed. See blocked headers list below for restricted header names.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="logic" type="object">
  Update the conditional logic for webhook triggering.
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X PUT 'https://api.opnform.com/open/forms/123/integrations/42' \
    -H 'Authorization: Bearer YOUR_PAT' \
    -H 'Content-Type: application/json' \
    -d '{
      "integration_id": "webhook",
      "status": "active",
      "data": {
        "webhook_url": "https://new-endpoint.com/opnform-hook",
        "webhook_secret": "whsec_newsecret123456789abcdef",
        "webhook_headers": {
          "X-API-Key": "new-api-key",
          "X-Custom-ID": "updated-value"
        }
      }
    }'
  ```
</RequestExample>

## Response

`200 OK` – Webhook updated successfully.

<ResponseExample>
  ```json Success theme={null}
  {
    "message": "Form Integration was updated.",
    "form_integration": {
      "id": 42,
      "form_id": 123,
      "integration_id": "webhook",
      "status": "active",
      "data": {
        "webhook_url": "https://new-endpoint.com/opnform-hook",
        "webhook_secret": "whsec_newsecret123456789abcdef",
        "webhook_headers": {
          "X-API-Key": "new-api-key",
          "X-Custom-ID": "updated-value"
        }
      }
    }
  }
  ```
</ResponseExample>

`403 Forbidden` – The token does not have `manage-integrations` ability or insufficient form permissions.

`404 Not Found` – Form or integration not found.

`422 Unprocessable Entity` – Validation error.

<ResponseExample>
  ```json Error theme={null}
  {
    "message": "The given data was invalid.",
    "errors": {
      "data.webhook_url": ["The webhook URL must use HTTPS."],
      "data.webhook_secret": ["The webhook secret must be at least 12 characters."],
      "data.webhook_headers": ["The 'Authorization' header cannot be customized for security reasons."]
    }
  }
  ```
</ResponseExample>

## Security

Webhook URLs are validated when they are saved and again before each delivery. OpnForm does not follow webhook redirects, and private network destinations are blocked unless the instance operator explicitly enables private webhook URLs for a self-hosted deployment.

### Secret Rotation

When updating the `webhook_secret`, the new secret will be used for all future webhook requests. Existing webhook attempts with the old secret will fail validation on the receiver's end.

If you need to rotate your secret, consider implementing a grace period on your receiving endpoint to accept both old and new secrets during the transition.

### Blocked Headers

For security reasons, the following headers cannot be customized in `webhook_headers`:

* `Authorization`
* `X-Webhook-Signature`
* `Content-Type`
* `Content-Length`
* `Host`
* `Cookie`
* `X-CSRF-Token`
* `X-Forwarded-For`
* `X-Forwarded-Proto`
* `X-Real-IP`

For signature validation implementation examples, see [Validating Webhook Signatures](/api-reference/integrations/webhook-security).


## OpenAPI

````yaml put /open/forms/{form}/integrations/{integrationid}
openapi: 3.0.1
info:
  title: OpnForm API
  description: API for interacting with OpnForm, primarily used for Zapier integration
  version: 1.0.0
servers:
  - url: https://api.opnform.com
security:
  - bearerAuth: []
tags:
  - name: Workspaces
    description: Create and manage workspaces.
  - name: Workspace Users
    description: Manage users within a workspace.
  - name: Forms
    description: Manage and retrieve forms.
  - name: Submissions
    description: Access and manage form submissions.
  - name: Integrations
    description: Manage form integrations (webhooks) via API.
  - name: Zapier
    description: Legacy endpoints for the Zapier integration.
paths:
  /open/forms/{form}/integrations/{integrationid}:
    put:
      tags:
        - Integrations
      summary: Update Webhook Integration
      description: >-
        Update an existing webhook integration. Requires `manage-integrations`
        ability.
      parameters:
        - name: form
          in: path
          required: true
          schema:
            type: number
            description: The ID of the form.
        - name: integrationid
          in: path
          required: true
          schema:
            type: number
            description: The ID of the integration.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - integration_id
                - data
              properties:
                integration_id:
                  type: string
                  enum:
                    - webhook
                  description: Must be "webhook"
                status:
                  type: string
                  enum:
                    - active
                    - inactive
                  description: The status of the webhook
                data:
                  type: object
                  required:
                    - webhook_url
                  properties:
                    webhook_url:
                      type: string
                      format: uri
                      description: The URL where submissions will be sent
      responses:
        '200':
          description: Webhook updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Form Integration was updated.
                  form_integration:
                    $ref: '#/components/schemas/FormIntegration'
        '403':
          description: Forbidden – insufficient permissions
        '404':
          description: Form or integration not found
        '422':
          description: Validation error
      security:
        - bearerAuth: []
components:
  schemas:
    FormIntegration:
      type: object
      properties:
        id:
          type: number
          description: Unique identifier for the integration.
          readOnly: true
        form_id:
          type: number
          description: The ID of the associated form.
          readOnly: true
        integration_id:
          type: string
          description: >-
            Type of integration exposed via API, including "webhook" and the
            provider-specific "make" integration.
          example: webhook
        status:
          type: string
          enum:
            - active
            - inactive
          description: Whether the integration is active.
        data:
          type: object
          description: >-
            Integration-specific configuration. For webhooks, contains
            webhook_url.
          example:
            webhook_url: https://example.com/opnform-hook
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Personal Access Token
      x-bearer-scopemap:
        workspaces-read: Read access to workspaces
        workspaces-write: Write access to workspaces
        workspace-users-read: Read access to workspace users
        workspace-users-write: Write access to workspace users
        forms-read: Read access to forms
        forms-write: Write access to forms
        manage-integrations: Manage form integrations (webhooks)

````