Private beta Request access

Hooks

REST hook subscriptions used by automation platforms (Zapier, Make). formcel POSTs a JSON payload to the target URL whenever the subscribed event happens.

Subscribe to an event

POST /api/v1/hooks/subscribe

Registers a target URL that receives a POST whenever the event happens on the form. Subscribing again with the same form, event, source and URL returns the existing subscription.

Service account scope: hooks:manage

Request body

form_id string required
target_url string (uri) required
Public HTTPS URL that receives the events.
event string required
submission.updated is accepted but not currently sent. One of submission.created, submission.status_changed, submission.deleted, submission.updated
source string required
One of zapier, make

Example request

curl -X POST "https://acme.formcel.com/api/v1/hooks/subscribe" \
  -H "Authorization: Bearer $FORMCEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"form_id":"frm_8f2c","target_url":"https://hooks.zapier.com/hooks/standard/123/abc","event":"submission.created","source":"zapier"}'

Responses

  • 201 The subscription.
  • 400 The request body or parameters are invalid.
  • 401 The API key is missing or invalid.
  • 403 The caller lacks access to the resource, or the service account lacks the required scope.
  • 404 The resource does not exist.

Response body HookSubscription

id string required
form_id string required
event string required
url string required
active boolean required
source string required

Unsubscribe

DELETE /api/v1/hooks/{id}

Removes a subscription created with subscribeHook. Webhooks created in the formcel app cannot be removed through this endpoint.

Service account scope: hooks:manage

path parameters

id string required
Subscription ID returned by subscribeHook.

Example request

curl -X DELETE "https://acme.formcel.com/api/v1/hooks/ID" \
  -H "Authorization: Bearer $FORMCEL_API_KEY"

Responses

  • 204 The subscription was removed.
  • 400 The request body or parameters are invalid.
  • 401 The API key is missing or invalid.
  • 403 The caller lacks access to the resource, or the service account lacks the required scope.
  • 404 The resource does not exist.

Events

The payloads POSTed to a subscription's target URL.

submission.created

A submission was received. Sent after a respondent submits the form. For forms that collect a payment it is sent once the payment completes.

event string required
form_id string required
data object required
The answers keyed by field.
submission object required

submission

id string required
form_id string required
schema_version integer required
created_at string (date-time) required

submission.status_changed

A submission's status changed. Sent when a submission moves to another status. A bulk status change in the formcel app sends one event with submission_ids instead of submission_id and previous_status.

event string required
form_id string required
submission_id string
submission_ids array of string
Sent instead of submission_id for bulk changes.
previous_status string
new_status string required

submission.deleted

A submission was deleted.

event string required
form_id string required
submission_id string required