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
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:
{
"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
POST /forms/{form}/webhooks
Content-Type: application/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:
{
"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
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
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
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
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.
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
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
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:
{
"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
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 |
