A
Atlas
...

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

  • Go to Form Settings → General (under Delivery Settings)
  • Enter your Webhook URL (e.g., https://yourserver.com/webhook)
  • Save
  • 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

    json
    {
      "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:

    HeaderDescription
    Content-Typeapplication/json
    X-Webhook-AttemptAttempt number (1, 2, 3...)
    X-Submission-IdThe submission ID
    X-Webhook-Signaturesha256=, only when the project has a webhook secret

    Automatic background retries (see Retry Behavior) send a different set:

    HeaderDescription
    Content-Typeapplication/json
    X-Atlas-Submission-IDThe submission ID
    X-Atlas-TimestampMilliseconds since the Unix epoch
    X-Atlas-SignatureHex HMAC-SHA256 of .
    X-Atlas-Priority, X-Atlas-Attempt, X-Atlas-Max-RetriesOnly 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:

  • Use an unguessable webhook URL (for example, include a long random token in the path or query string) and reject requests that don't match it
  • Treat the payload as untrusted input
  • If you need to confirm a submission is real, fetch it with GET /api/v1/submissions/{id} using your project API key
  • If a secret is configured for your project, verify X-Webhook-Signature like this:

    javascript
    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

    python
    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

    php
    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:

    PlanBackground retries
    All plansUp to 5
    With the Priority Webhooks add-onUp 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:

  • Respond within 30 seconds
  • Return a 2xx status code (200, 201, 204)
  • Handle duplicate deliveries idempotently
  • 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

    bash
    ngrok http 3000
    # Use the ngrok URL as your webhook URL

    Using RequestBin

  • Go to requestbin.com
  • Create a bin and copy the URL
  • Use it as your webhook URL for testing
  • 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:

    bash
    curl "https://atlasforms.app/api/v1/files/{file_id}" \
      -H "Authorization: Bearer fep_your_api_key"

    Best Practices

  • Use an unguessable URL - Prevents spoofed webhooks while signing secrets can't be set
  • Respond quickly - Do heavy processing async
  • Handle duplicates - Use submission ID as idempotency key
  • Log everything - Makes debugging easier
  • Use queues - Process webhooks in background jobs