# Verify webhooks

Canonical page: https://docs.ovok.com/signals/standalone/verify-webhooks

Learn how to verify a Signals webhook and what Signals expects from your endpoint. Deliveries follow [Standard Webhooks](https://www.standardwebhooks.com/); create the subscriber and pick its events in [Signals webhooks](/signals/standalone/webhooks).

## What Signals sends [#what-signals-sends]

Each delivery is a `POST` with a JSON body and these headers:

| Header | Value |
| --- | --- |
| `webhook-id` | The event's id. It stays the same on every retry. |
| `webhook-timestamp` | When this attempt was sent, in Unix seconds. Each retry is stamped again. |
| `webhook-signature` | `v1,<signature>`, one entry per active secret, separated by spaces. |
| `x-actimi-custom` | The subscriber's `custom` value, when you set one. |

The body is `{ "type", "timestamp", "sequence", "data" }`. Payloads are in [Event payloads](/signals/standalone/webhooks#event-payloads).

Each signature is the base64 HMAC-SHA256 of `{webhook-id}.{webhook-timestamp}.{raw body}`. The key is the secret's bytes: drop the `whsec_` prefix and base64-decode the rest.

## Verify each delivery [#verify-each-delivery]

Use the subscriber's `signingSecret` (`whsec_…`). Verify against the raw body, not re-serialized JSON, and compare in constant time. The Standard Webhooks libraries do both, and reject a `webhook-timestamp` more than 5 minutes from your clock; Signals sets no tolerance of its own.

<Tabs items={["Node.js", "Python", "Java"]} groupId="language" persist>
<Tab value="Node.js">

```ts title="webhook.ts"
import express from 'express';
import { Webhook } from 'standardwebhooks';

const webhook = new Webhook(process.env.SIGNALS_SIGNING_SECRET!);
const app = express();

app.post('/signals/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  let event;
  try {
    event = webhook.verify(req.body, req.headers as Record<string, string>);
  } catch {
    return res.sendStatus(400);
  }
  res.sendStatus(204);
  handle(event);
});
```

</Tab>
<Tab value="Python">

```python title="webhook.py"
import os
from flask import Flask, request
from standardwebhooks.webhooks import Webhook

webhook = Webhook(os.environ["SIGNALS_SIGNING_SECRET"])
app = Flask(__name__)

@app.post("/signals/webhook")
def receive():
    try:
        event = webhook.verify(request.get_data(), dict(request.headers))
    except Exception:
        return "", 400
    handle(event)
    return "", 204
```

</Tab>
<Tab value="Java">

```java title="SignalsWebhook.java"
import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.time.Instant;
import java.util.Base64;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;

public final class SignalsWebhook {
  private static final long TOLERANCE_SECONDS = 300;

  /** id, timestamp and signatures are the webhook-id, webhook-timestamp and webhook-signature headers. */
  public static boolean verify(String secret, String id, String timestamp, String signatures, String body)
      throws Exception {
    long sentAt = Long.parseLong(timestamp);
    if (Math.abs(Instant.now().getEpochSecond() - sentAt) > TOLERANCE_SECONDS) return false;
    byte[] key = Base64.getDecoder().decode(secret.substring("whsec_".length()));
    Mac mac = Mac.getInstance("HmacSHA256");
    mac.init(new SecretKeySpec(key, "HmacSHA256"));
    byte[] expected = mac.doFinal((id + "." + timestamp + "." + body).getBytes(StandardCharsets.UTF_8));
    for (String signature : signatures.split(" ")) {
      if (!signature.startsWith("v1,")) continue;
      if (MessageDigest.isEqual(expected, Base64.getDecoder().decode(signature.substring(3)))) return true;
    }
    return false;
  }
}
```

</Tab>
</Tabs>

## Rotate the secret [#rotate-the-secret]

[`rotate-secret`](/api/signals-api---clients/rotate-the-webhook-signing-secret) returns the new secret once. The old one keeps signing for 24 hours, so `webhook-signature` carries both and a receiver with either secret verifies. Rotate again only after your receiver uses the new secret.

## Answer the delivery [#answer-the-delivery]

- Answer `2xx` within 15 seconds and do the work afterwards. Any other status, a timeout or a connection error is a failure.
- Redirects are not followed; a `3xx` is a failure.
- `410 Gone` is not retried: Signals turns the endpoint off. See [When deliveries fail](/signals/standalone/webhooks#when-deliveries-fail).
- A `Retry-After` header (at most 24 hours) sets a minimum wait before the next attempt.

## Retries [#retries]

Signals makes up to 10 attempts per event. After a failure it waits about 5 seconds, 5 minutes, 30 minutes, 2, 5, 10, 14, 20 and 24 hours, each with up to 20% added. After the tenth failure the event is marked failed; [redeliver it](/api/signals-api---events/redeliver-one-event) once the receiver is fixed.

By default an `alert.*` event older than 15 minutes is dropped instead of sent, so a late retry never reads as a fresh alarm. A redelivery you ask for is sent whatever its age.

## Duplicates and order [#duplicates-and-order]

- A delivery can arrive more than once. Treat `webhook-id` as the idempotency key and skip one you have handled.
- Signals sends a subscriber's events in parallel, so they can arrive out of order. Order by `sequence`, and for an alert ignore a delivery whose `data.version` is lower than one you handled.

## Related [#related]

- [Signals webhooks](/signals/standalone/webhooks)
- [Webhooks over mutual TLS](/signals/standalone/mtls#webhooks-over-mutual-tls)
- [Signals standalone](/signals/standalone)
