Webhooks API

REST-hook subscribe / unsubscribe for new form submissions.

Overview

When a source activates, Pipedream calls subscribe with its HTTP endpoint. On each new submission for that form, Minform POSTs the automation payload to targetUrl. Deactivate calls unsubscribe with the returned hook id.

Supported event: submission.created (default). Subscribe requires read:submissions.

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

Request body (JSON)

Field	Required	Description
`formId`	Yes	Form slug
`targetUrl`	Yes	HTTPS URL that will receive POSTs
`event`	No	Default `submission.created`

{
  "formId": "contact-form",
  "targetUrl": "https://....m.pipedream.net",
  "event": "submission.created"
}

Headers

Authorization: Bearer …
Content-Type: application/json

Response

{
  "id": "01J...",
  "formId": "contact-form",
  "event": "submission.created",
  "targetUrl": "https://....m.pipedream.net"
}

Store id for unsubscribe. User must have access to the form or subscribe fails.

Unsubscribe

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

Query param	Required	Description
`hook_id`	Yes	`id` from subscribe response

{ "success": true }

404 if the hook does not exist or belongs to another user.

Delivery payload

On submission.created, Minform sends:

Method: POST
Header: Content-Type: application/json
Body: a JSON array with one object (same shape as /results)

[
  {
    "id": "01JABC...",
    "created_at": "2026-03-01T12:00:00.000Z",
    "form_id": "contact-form",
    "form_name": "Contact Form",
    "Name": "John Doe",
    "Email": "john@example.com",
    "Message": "Hello!"
  }
]

Always treat the body as an array. Field answers are flat label keys (snake_case for fixed fields: created_at, form_id, form_name). Failed deliveries are retried with backoff (several attempts before give-up).

Errors

Status	When
400	Missing `formId`/`targetUrl` or `hook_id`
401	Missing or invalid token
403	Missing `read:submissions` (subscribe)
404	Hook not found (delete)
500	Server error

Best practices

Return 2xx quickly; process work asynchronously in Pipedream.
Handle retries idempotently using submission id.
Always unsubscribe on source deactivate to avoid orphan hooks.