Webhooks
Webhooks notify your server when submissions arrive. Configure a URL and Atlas will POST submission data to it as each submission is received.
Configuration
https://yourserver.com/webhook)To send every form in a project to the same URL, set Default Webhook URL in Project Settings → Defaults. A form's own webhook URL takes precedence over the project default.
Webhooks are available on every plan, including Starter.
Webhook Payload
{
"event": "submission.created",
"timestamp": "2024-01-15T10:30:00.000Z",
"form": {
"id": "form-uuid",
"public_id": "abc123xyz",
"slug": "contact",
"name": "Contact Form"
},
"submission": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"data": {
"name": "John Doe",
"email": "john@example.com",
"message": "Hello!"
},
"files": [
{
"id": "file-uuid",
"field": "attachment",
"filename": "document.pdf",
"type": "application/pdf",
"size": 102400
}
],
"metadata": {
"ip": "192.168.1.1",
"user_agent": "Mozilla/5.0...",
"submitted_from": "https://atlasforms.app/f/abc123xyz"
},
"created_at": "2024-01-15T10:30:00.000Z"
}
}Webhook Headers
The first delivery attempt (made while the form submission is being processed) and manual retries from the dashboard include:
| Header | Description |
|---|---|
Content-Type | application/json |
X-Webhook-Attempt | Attempt number (1, 2, 3...) |
X-Submission-Id | The submission ID |
X-Webhook-Signature | sha256=, only when the project has a webhook secret |
Automatic background retries (see Retry Behavior) send a different set:
| Header | Description |
|---|---|
Content-Type | application/json |
X-Atlas-Submission-ID | The submission ID |
X-Atlas-Timestamp | Milliseconds since the Unix epoch |
X-Atlas-Signature | Hex HMAC-SHA256 of . |
X-Atlas-Priority, X-Atlas-Attempt, X-Atlas-Max-Retries | Only with the Priority Webhooks add-on |
Signature Verification
Atlas can sign webhooks with HMAC-SHA256 using a per-project webhook secret. The dashboard and API do not currently let you set or view that secret, so in practice deliveries are not signed with a secret you know. Until that changes:
GET /api/v1/submissions/{id} using your project API keyIf a secret is configured for your project, verify X-Webhook-Signature like this:
const crypto = require('crypto');
function verifyWebhook(payload, signature, secret) {
const expected = 'sha256=' + crypto
.createHmac('sha256', secret)
.update(payload)
.digest('hex');
return crypto.timingSafeEqual(
Buffer.from(signature),
Buffer.from(expected)
);
}
// Express.js example
app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
const signature = req.headers['x-webhook-signature'];
const payload = req.body.toString();
if (!verifyWebhook(payload, signature, process.env.WEBHOOK_SECRET)) {
return res.status(401).send('Invalid signature');
}
const data = JSON.parse(payload);
console.log('New submission:', data.submission.id);
res.status(200).send('OK');
});Python Example
import hmac
import hashlib
def verify_webhook(payload: bytes, signature: str, secret: str) -> bool:
expected = 'sha256=' + hmac.new(
secret.encode(),
payload,
hashlib.sha256
).hexdigest()
return hmac.compare_digest(signature, expected)PHP Example
function verifyWebhook($payload, $signature, $secret) {
$expected = 'sha256=' . hash_hmac('sha256', $payload, $secret);
return hash_equals($expected, $signature);
}Retry Behavior
Atlas makes the first delivery attempt before it responds to the form submission. If your server doesn't return a 2xx status within 30 seconds, the delivery is queued and retried in the background with exponential backoff:
| Plan | Background retries |
|---|---|
| All plans | Up to 5 |
| With the Priority Webhooks add-on | Up to 10 |
Background retries can be skipped while Atlas is throttling its background job queue. Redirects (3xx) are not followed and count as a failure.
The webhook status shown in the dashboard (success or failed) reflects the first attempt and any manual retries. To retry by hand, click the failed webhook status next to the submission in your dashboard's submission list.
Response Requirements
Your webhook endpoint should:
2xx status code (200, 201, 204)Redirect Parameter
If the form has a Success Redirect, the redirect URL includes webhook=delivered when the first attempt succeeded and webhook=pending otherwise. JSON responses include webhook_delivered (true or false).
Testing Webhooks
Using ngrok
ngrok http 3000
# Use the ngrok URL as your webhook URLUsing RequestBin
Manual Retry
In your dashboard's submission list, click the failed webhook status next to a submission to resend it. Manual retries don't include the files array.
Accessing Files
Files in the webhook payload include IDs, not URLs. To get a download link, request the file with your project API key. The response contains a signed url that expires after one hour:
curl "https://atlasforms.app/api/v1/files/{file_id}" \
-H "Authorization: Bearer fep_your_api_key"