Home/Webhooks

Webhooks API

Subscribe to and manage form submission events via webhooks.

Overview

Minform's webhooks API allows you to subscribe to events such as new form submissions. When an event occurs, Minform will send an HTTP POST request to your specified URL with information about the event.

These webhooks are primarily used by Pipedream to trigger zaps when new form submissions are received.

Create Webhook Subscription

POSThttps://minform.io/api/pipedream/hooks

Subscribe to events for a specific form.

Request Body

Parameter	Type	Required	Description
`formId`	String	Yes	The slug identifier of the form to subscribe to
`targetUrl`	String	Yes	The URL to send webhooks to when events occur
`event`	String	No	The event to subscribe to. Default: `submission.created`

{
  "formId": "contact-form",
  "targetUrl": "https://hooks.pipedream.com/hooks/catch/123456/abcdef/",
  "event": "submission.created"
}

Headers

Header	Required	Description
`Authorization`	Yes	Bearer token for authentication. Format: `Bearer <token>`
`Content-Type`	Yes	Must be set to `application/json`

Response

The response contains details about the created webhook subscription:

{
  "id": "60a1b2c3d4e5f6g7h8i9j0k",
  "formId": "contact-form",
  "event": "submission.created",
  "targetUrl": "https://hooks.pipedream.com/hooks/catch/123456/abcdef/"
}

Property	Type	Description
`id`	String	Unique identifier for the webhook subscription
`formId`	String	The slug identifier of the subscribed form
`event`	String	The event type subscribed to
`targetUrl`	String	The URL that will receive webhook notifications

Note: This endpoint requires the read:submissions scope.

Delete Webhook Subscription

DELETEhttps://minform.io/api/pipedream/hooks?hook_id=id

Unsubscribe from a previously created webhook subscription.

Query Parameters

Parameter	Type	Required	Description
`hook_id`	String	Yes	The ID of the webhook subscription to delete

Headers

Header	Required	Description
`Authorization`	Yes	Bearer token for authentication. Format: `Bearer <token>`

Response

The response indicates whether the deletion was successful:

{
  "success": true
}

Webhook Payload

When a form submission is created, Minform will send a webhook POST request to your specified URL with the following payload:

{
  "id": "submission_123456",
  "createdAt": "2023-08-01T12:00:00Z",
  "formId": "contact-form",
  "formName": "Contact Form",
  "fields": {
    "name": { 
      "value": "John Doe", 
      "label": "Name", 
      "type": "inputShort" 
    },
    "email": { 
      "value": "john@example.com", 
      "label": "Email", 
      "type": "inputEmail" 
    },
    "message": { 
      "value": "Hello! I'd like more information.", 
      "label": "Message", 
      "type": "inputLong" 
    }
  }
}

This payload matches the format returned by the form submissions API.

Error Responses

The API may return the following error responses:

Status Code	Error	Description
400	Bad Request	The request was invalid or missing required fields
401	Unauthorized	Authentication failed or was not provided
403	Forbidden	The authenticated user doesn't have permission to access the form
404	Not Found	The specified form or webhook was not found
500	Server Error	An error occurred on the server

Webhook Best Practices

Verify your webhooks: For security, validate that webhooks are coming from Minform.
Respond quickly: Your webhook endpoint should respond with a 2xx status code as quickly as possible.
Handle retries: Minform will retry failed webhook deliveries several times before giving up.
Process webhooks asynchronously: To avoid timeouts, process webhooks in the background after acknowledging receipt.