# Webhooks

> We POST each new submission to your HTTPS endpoint as signed JSON, and retry until you answer with a 2xx.

Last updated 2026-11-14. Web version: https://wrenform.com/docs/webhooks

```http
POST /your/webhook HTTP/1.1
Content-Type: application/json
User-Agent: Wrenform-Webhooks/1.0 (+https://wrenform.com/docs/webhooks)
webhook-id: 01JD3K2M9X7Q8R4T5V6W7Y8Z9A
webhook-timestamp: 1765880100
webhook-signature: v1,K5oZfzN95Z9UVu1EsfQmfVNQhnkZ2pj9o9NDN/H/pI4=
```

```json
{
  "type": "submission.created",
  "test": false,
  "createdAt": "2026-12-18T10:15:00.000Z",
  "data": {
    "id": "01JD3K2M9X7Q8R4T5V6W7Y8Z9A",
    "form": { "id": "AbC123xYz789", "name": "Contact – example.com" },
    "receivedAt": "2026-12-18T10:15:00.000Z",
    "replyTo": "ada@example.com",
    "fields": { "name": "Ada", "email": "ada@example.com", "message": "Hello", "topics": ["sales", "support"] },
    "meta": { "origin": "https://example.com", "referer": "https://example.com/contact", "userAgent": "Mozilla/5.0 …" },
    "dashboardUrl": "https://wrenform.com/app/submissions/01JD3K2M9X7Q8R4T5V6W7Y8Z9A"
  }
}
```

Webhooks are on the Pro (€12/month) and Agency (€29/month) plans. Each form can have up to 3 endpoints.

## Steps

1. Open the form's **Webhooks** page and add your endpoint URL. It must be `https://` and reachable on the public internet.
2. Copy the signing secret. It starts with `whsec_` and is shown once; you can reveal it again later from the same page.
3. Verify the signature on every request (below), then answer with any `2xx` status within 10 seconds.
4. Do slow work (sending to a CRM, Slack and so on) after you answer, or in a queue.

## The payload

- `type` is always `submission.created` for now. `test` is `true` for test sends from the dashboard.
- `data.id` is the submission ID. `data.form.id` is the form ID from your snippet.
- `fields` keeps the order the visitor sent. Values are strings, or lists of strings for repeated names. Reserved fields such as `_honey` are not included.
- `replyTo`, `meta.origin`, `meta.referer` and `meta.userAgent` can be `null`.
- We send webhooks only for submissions that land in Inbox. Spam, and submissions over your monthly quota, get none.

## Verify the signature

We sign with the [Standard Webhooks](https://www.standardwebhooks.com) scheme:

1. Build the signed content: `webhook-id` + `.` + `webhook-timestamp` + `.` + the raw request body.
2. Compute an HMAC-SHA256 of it. The key is the part of your secret after `whsec_`, base64-decoded.
3. Base64-encode the result. `webhook-signature` holds one or more space-separated `v1,<signature>` entries; accept the request if any one matches, comparing in constant time. There are two entries for 24 hours after you rotate the secret.
4. Reject the request if `webhook-timestamp` is more than 5 minutes from your clock.

Use the raw body exactly as received. Parsing and re-serialising the JSON changes the bytes and breaks the signature.

```js
import { createHmac, timingSafeEqual } from "node:crypto";

// headers: lower-case names, as Node gives them. rawBody: the body as a string, before any JSON parsing.
export function verifyWebhook(headers, rawBody, secret) {
  const id = headers["webhook-id"];
  const timestamp = headers["webhook-timestamp"];
  const signatures = headers["webhook-signature"];
  if (!id || !timestamp || !signatures) return false;

  const now = Math.floor(Date.now() / 1000);
  if (!/^\d+$/.test(timestamp) || Math.abs(now - Number(timestamp)) > 5 * 60) return false;

  const key = Buffer.from(secret.replace(/^whsec_/, ""), "base64");
  const expected = createHmac("sha256", key).update(`${id}.${timestamp}.${rawBody}`).digest();

  return signatures.split(" ").some((entry) => {
    const [version, signature] = entry.split(",");
    if (version !== "v1" || !signature) return false;
    const received = Buffer.from(signature, "base64");
    return received.length === expected.length && timingSafeEqual(received, expected);
  });
}
```

```python
import base64, hashlib, hmac, time

# headers: a case-insensitive mapping (Flask/Django request.headers). raw_body: bytes, before JSON parsing.
def verify_webhook(headers, raw_body: bytes, secret: str) -> bool:
    msg_id = headers.get("webhook-id")
    timestamp = headers.get("webhook-timestamp")
    signatures = headers.get("webhook-signature")
    if not (msg_id and timestamp and signatures) or not timestamp.isdigit():
        return False
    if abs(time.time() - int(timestamp)) > 5 * 60:
        return False

    key = base64.b64decode(secret.removeprefix("whsec_"))
    signed = f"{msg_id}.{timestamp}.".encode() + raw_body
    expected = base64.b64encode(hmac.new(key, signed, hashlib.sha256).digest()).decode()

    for entry in signatures.split(" "):
        version, _, signature = entry.partition(",")
        if version == "v1" and hmac.compare_digest(signature, expected):
            return True
    return False
```

```php
<?php
// $headers: lower-case names. $rawBody: file_get_contents('php://input').
function verify_webhook(array $headers, string $rawBody, string $secret): bool {
    $id = $headers['webhook-id'] ?? '';
    $timestamp = $headers['webhook-timestamp'] ?? '';
    $signatures = $headers['webhook-signature'] ?? '';
    if ($id === '' || $signatures === '' || !ctype_digit($timestamp)) return false;
    if (abs(time() - (int) $timestamp) > 5 * 60) return false;

    $key = base64_decode(preg_replace('/^whsec_/', '', $secret));
    $expected = base64_encode(hash_hmac('sha256', "$id.$timestamp.$rawBody", $key, true));

    foreach (explode(' ', $signatures) as $entry) {
        [$version, $signature] = array_pad(explode(',', $entry, 2), 2, '');
        if ($version === 'v1' && hash_equals($expected, $signature)) return true;
    }
    return false;
}

$headers = array_change_key_case(getallheaders(), CASE_LOWER);
if (!verify_webhook($headers, file_get_contents('php://input'), getenv('WRENFORM_WEBHOOK_SECRET'))) {
    http_response_code(401);
    exit;
}
```

```go
package webhooks

import (
	"crypto/hmac"
	"crypto/sha256"
	"encoding/base64"
	"net/http"
	"strconv"
	"strings"
	"time"
)

// VerifyWebhook checks a Wrenform delivery. rawBody is the body before any JSON decoding.
func VerifyWebhook(h http.Header, rawBody []byte, secret string) bool {
	id, timestamp, signatures := h.Get("webhook-id"), h.Get("webhook-timestamp"), h.Get("webhook-signature")
	if id == "" || timestamp == "" || signatures == "" {
		return false
	}
	ts, err := strconv.ParseInt(timestamp, 10, 64)
	if err != nil {
		return false
	}
	if d := time.Now().Unix() - ts; d > 5*60 || d < -5*60 {
		return false
	}
	key, err := base64.StdEncoding.DecodeString(strings.TrimPrefix(secret, "whsec_"))
	if err != nil {
		return false
	}
	mac := hmac.New(sha256.New, key)
	mac.Write([]byte(id + "." + timestamp + "."))
	mac.Write(rawBody)
	expected := mac.Sum(nil)

	for _, entry := range strings.Split(signatures, " ") {
		version, signature, ok := strings.Cut(entry, ",")
		if !ok || version != "v1" {
			continue
		}
		got, err := base64.StdEncoding.DecodeString(signature)
		if err == nil && hmac.Equal(got, expected) {
			return true
		}
	}
	return false
}
```

The Standard Webhooks project also publishes libraries that do this for you; pass them your `whsec_` secret.

In Express, read the raw body with `express.raw({ type: "application/json" })` and pass `req.body.toString("utf8")`. In Next.js route handlers, use `await request.text()`.

## Delivery and retries

| Topic | Rule |
|---|---|
| Success | Any `2xx` response within 10 seconds |
| Failure | Any other status, a timeout, or a TLS, DNS or connection error |
| Retries | After 1 min, 5 min, 30 min, 2 h, 6 h and 12 h: 7 attempts over about 21 hours. Then the delivery is abandoned |
| Auto-disable | After 50 failed deliveries in a row, or 3 days of failures with no success. We email you; re-enable it on the Webhooks page |
| Order | Not guaranteed |
| Duplicates | Possible (at least once). De-duplicate by `webhook-id`; it stays the same across retries |
| Network | HTTPS only, public IP addresses only. Redirects are not followed: a `3xx` is a failure |

The Webhooks page shows each delivery with its status code and the start of your response. You can retry an abandoned delivery, send a test, rotate the secret, or turn an endpoint off.

## Test it

Press **Send test** on the Webhooks page. You get a real, signed request with `"test": true`, and the page shows your response.

## Common problems

- **Every signature fails.** Your framework parsed the JSON before you read the body. Verify against the raw bytes.
- **Fails only sometimes.** Your server's clock is off by more than 5 minutes. Sync it with NTP.
- **The URL is refused.** It isn't `https://`, or it points to a private, local or reserved address.
- **Deliveries time out.** Answer first, then do the work. We wait 10 seconds at most.
- **A `3xx` counts as a failure.** Use the final URL, including the trailing slash if your server redirects to it.

## Next steps

- [Errors](/docs/errors): codes the form endpoint returns.
- [Privacy](/docs/privacy): what a webhook sends to your server, for your records.
