All docs

API reference: Webhooks

Manage webhooks, list deliveries, and replay failures.

Updated . 5 min read.

Webhooks let you POST every submission to your own endpoint. Each form has its own list of webhooks. All endpoints require a bearer token.

Base URL: https://formspring.io/api/v1

Method Path Ability
GET /forms/{form}/webhooks webhooks:read
POST /forms/{form}/webhooks webhooks:write
GET /forms/{form}/webhooks/{webhook} webhooks:read
PUT /forms/{form}/webhooks/{webhook} webhooks:write
DELETE /forms/{form}/webhooks/{webhook} webhooks:write
GET /forms/{form}/webhooks/{webhook}/deliveries webhooks:read
POST /forms/{form}/webhooks/{webhook}/deliveries/{delivery}/replay webhooks:write

List webhooks

http
GET /forms/{form}/webhooks

Returns every webhook attached to the form, including its signing secret hash (the actual secret was returned only at creation time - see below).

Response 200:

json
{
  "data": [
    {
      "id": "wh_01H...",
      "label": "Production Slack",
      "provider": "slack",
      "url": "https://hooks.slack.com/services/...",
      "active": true,
      "config": { "channel": "#submissions" },
      "secret_last4": "a1f3",
      "created_at": "2026-01-12T09:00:00Z"
    }
  ]
}

Create a webhook

http
POST /forms/{form}/webhooks
Content-Type: application/json
json
{
  "label": "Production Slack",
  "provider": "slack",
  "url": "https://hooks.slack.com/services/...",
  "config": { "channel": "#submissions" }
}

provider is optional. Set it to one of slack, discord, teams, zapier, make, webhook (default) to format the payload for that target. Plain webhook posts the raw submission JSON.

Response 201:

json
{
  "data": { "id": "wh_01H...", "label": "Production Slack", ... },
  "secret": "whsec_abc123def456..."
}

The plaintext secret is shown once and never again. Save it somewhere your endpoint can access it. The secret is used to compute the X-Formspring-Signature header on every delivery so you can verify authenticity.

Show a webhook

http
GET /forms/{form}/webhooks/{webhook}

Returns the same shape as the list endpoint. The plaintext secret is never returned again - only secret_last4.

Update a webhook

http
PUT /forms/{form}/webhooks/{webhook}
Content-Type: application/json

Send only the fields you want to change. To rotate the signing secret use the rotate endpoint below.

Response 200: updated WebhookResource.

Inspect a delivery

http
GET /forms/{form}/webhooks/{webhook}/deliveries/{delivery}/inspect

Requires webhooks:read. Returns the request that was made (destination host and path, headers, and the request body rebuilt from the submission and labelled as such), how it is signed (header, format, the string that is signed, and the key ids that apply), the response (status, body, error) and every attempt for the same submission, oldest first. For a sandbox workspace sandbox is true and the response is a fixture. To try your error handling, add sandbox_outcome to the webhook URL as a query parameter (https://example.com/hook?sandbox_outcome=rate_limited; a provider integration takes the same key in its config). The values are ok (default), bad_request, unauthorized, not_found, rate_limited, server_error, unavailable and timeout. A failed outcome records one failed delivery shaped like that provider's error (a timeout has no status and an error message) and is never retried.

Rotate the signing secret

http
POST /forms/{form}/webhooks/{webhook}/rotate-secret
Content-Type: application/json

{ "overlap_hours": 24 }

Requires webhooks:write. The response is the WebhookResource plus a fresh plaintext secret, shown once. The previous secret keeps signing for overlap_hours (0 to 168, default 24; 0 revokes it at once), so deliveries carry two v1 signatures and your receiver can switch without dropping events. signing_key_id, previous_signing_key_id and previous_secret_expires_at on the resource show where the rotation stands. Provider integrations answer 422.

http
DELETE /forms/{form}/webhooks/{webhook}/previous-secret

Ends an open overlap early so only the new secret signs. See Signing and verification.

Delete a webhook

http
DELETE /forms/{form}/webhooks/{webhook}

Removes the webhook. In-flight deliveries continue but no new submissions trigger the webhook.

Response 200: {"ok": true}

List deliveries

http
GET /forms/{form}/webhooks/{webhook}/deliveries?per_page=50

Every delivery attempt is recorded. Each entry has the request body, response status, response body (truncated to 4KB), latency, and retry count.

Response 200:

json
{
  "data": [
    {
      "id": "whd_01H...",
      "status": "succeeded",
      "http_status": 200,
      "attempts": 1,
      "duration_ms": 142,
      "submission_id": "subm_01H...",
      "request_body": { ... },
      "response_body": "ok",
      "delivered_at": "2026-05-07T12:34:56Z"
    }
  ]
}

status is one of pending, succeeded, failed, dead. A delivery becomes dead after retries are exhausted.

Replay a delivery

http
POST /forms/{form}/webhooks/{webhook}/deliveries/{delivery}/replay

Re-fires the same delivery against the webhook's current URL and config. The original delivery row is preserved; a new delivery row is created for the replay.

Use cases:

  • Your endpoint was down when the original fired.
  • You changed the webhook URL and want to send historical events to the new endpoint.
  • Debugging - you can replay the same payload against a tunnel like ngrok.

Response 200: {"ok": true, "delivery_id": "whd_02H..."}

Common errors

Status Meaning
400 Invalid URL (must be HTTPS), invalid provider, or config validation failed
401 Token missing or invalid
403 Token lacks webhooks:read or webhooks:write
404 Form, webhook, or delivery not found
429 API rate limit hit

What's next