Webhooks
Use webhooks when your backend needs to react to saved sessions, fills, renders, or test events without polling.
Create an endpoint
curl https://api.stackfill.com/v1/webhook_endpoints \
-H "Authorization: Bearer stackfill_live_sk_REPLACE_ME" \
-H "Content-Type: application/json" \
-d '{
"url": "https://example.com/webhooks/stackfill",
"events": ["embed_session.saved", "render.succeeded"],
"mode": "live"
}'
The signing secret is shown once. Store it immediately.
Events
Subscribe to one or more event types (or * for all):
| Event | Fires when |
|---|---|
embed_session.saved |
A storefront visitor saves a personalized design in the embed widget. |
fill.created |
A fill is created (hosted link or embed). |
render.succeeded |
A final render completes. |
batch.completed |
A CSV batch finishes; payload carries batch_id, template_id, row_count, rendered_count, failed_count. |
Verify signatures
StackFill signs webhook payloads with the endpoint signing secret. Reject unsigned requests and log the event.id for idempotency.
// Pseudocode: compare an HMAC over the raw request body with the signature header.
verifyStackFillSignature(rawBody, request.headers, signingSecret);
Current delivery behavior
Delivery attempts are recorded and can be listed. Retry scheduling, delivery detail, manual redelivery, and test endpoints are planned hardening work and should not be treated as complete yet.
Common errors
webhook_secrets_not_configured means the deployment is missing the webhook secret store.
invalid_webhook_url means the endpoint URL must be HTTPS.