ATLAS Webhooks are powered by Hook0, an open-source webhook infrastructure service. To ensure that incoming webhook events are genuine and originate from ATLAS, your application must verify the signature included with every webhook delivery. ATLAS signs each webhook using HMAC-SHA256 and sends the signature in the X-Hook0-Signature HTTP header.

Webhook requests must not be processed until this signature is verified.

1. How ATLAS Signs Webhooks (via Hook0)

For every webhook event:

1. Hook0 generates:

• a timestamp (t)

• a list of headers used in the signature (h)

• the raw JSON body

1. Hook0 constructs a signed_payload:

   signed_payload =
       timestamp + "." +
       headers_list + "." +
       header_values_joined + "." +
       raw_body

3. Hook0 computes:

   HMAC_SHA256(signed_payload, SIGNING_SECRET)

4. The resulting signature is included in the header:

   X-Hook0-Signature: t=...,h=...,v1=...

Only the v1 signature needs to be validated.

2. Your Responsibility: Verifying the Signature

When your server receives a webhook:

Step 1 — Read Signature Header

Read the entire X-Hook0-Signature header and extract:

• t (timestamp)

• h (space-separated list of headers)

• v1 (the signature)

Example:

t=1733399090,h=X-Event-Id X-Event-Type,v1=abcdef123456...

Step 2 — Rebuild the Signed Payload

1. From the value of h, split the header names.

2. Read each of these headers from the incoming HTTP request in the same order.

3. Join these values with "." to produce header_values_joined.

4. Concatenate:

signed_payload = t + "." + h + "." + header_values_joined + "." + raw_body

Important: Use the exact raw body as received (no formatting changes, whitespace changes, or re-serialization).

Step 3 — Compute Your Own HMAC

Using the signing secret from your Hook0 subscription:

expected_signature = HMAC_SHA256(signed_payload, SIGNING_SECRET)

Hex-encode the result.

Step 4 — Compare Signatures (Constant Time)

Compare:

• expected_signature

• v1 from X-Hook0-Signature

Use a constant-time comparison to prevent timing attacks.

If they do not match → reject the request.

Step 5 — Timestamp Check (Replay Protection)

Convert t to a UNIX timestamp and ensure:

now - t < 5 minutes

If the timestamp is too old → reject as a possible replay attack.

3. Summary

Before processing any webhook event, your server must:

1. Parse X-Hook0-Signature

2. Rebuild signed_payload

3. Compute HMAC-SHA256 using your signing secret

4. Compare with v1 (constant time)

5. Validate timestamp freshness

A webhook should be trusted only if all the steps above succeed.

4. Responding to webhooks Situation

What to return Signature valid, event accepted Any 2xx (e.g. 200 OK) Signature missing or invalid 401 Unauthorized A delivery counts as successful only if you return a 2xx status within 15 seconds (5 seconds to establish the TCP connection, 15 seconds in total). Anything else — a non-2xx status (including 4xx), a timeout, or a connection error — is treated as a failure and retried. Acknowledge first, process later. Verify the signature, store or enqueue the event, return 200 immediately, and do the actual work in a background job. Long-running processing inside the request handler leads to timeouts and unnecessary retries. Return 2xx for event types you do not handle, so they are not retried.

5. Retry policy

If a delivery fails, Hook0 retries it with increasing delays. The delay depends on how many attempts have already failed:

Retry # Delay before this retry Approx. time since first failure 1 3 seconds 3 s 2 10 seconds 13 s 3 3 minutes ~3 min 4 30 minutes ~33 min 5 1 hour ~1.5 h 6 3 hours ~4.5 h 7 5 hours ~9.5 h 8 – 24 10 hours each ~19.5 h → ~7.5 days Limits: up to 24 retries (25 delivery attempts including the first), within a maximum window of 8 days. With the schedule above, the last retry happens about 7.5 days after the first failure. Jitter: a small random delay is added to each wait (up to 10% of it, minimum 2 seconds, maximum 15 minutes), so retries are never earlier than the times above, but can be slightly later. After the last retry, the event is not delivered again automatically. Contact the ATLAS team if you need events to be replayed (for example, after an extended outage on your side).

6. Code Examples

.NET (C#)

using System.Security.Cryptography;
using Microsoft.AspNetCore.Mvc;

[ApiController]
[Route("webhooks/hook0")]
public class Hook0Webhook : ControllerBase
{
    private readonly string secret = "YOUR_SIGNING_SECRET";

    [HttpPost]
    public async Task<IActionResult> Receive()
    {
        var sigHeader = Request.Headers["X-Hook0-Signature"].ToString();
        if (string.IsNullOrEmpty(sigHeader)) return Unauthorized();

        string timestamp = null, headersList = null, sigV1 = null;

        foreach (var part in sigHeader.Split(','))
        {
            var kv = part.Split('=');
            if (kv.Length != 2) continue;

            if (kv[0] == "t") timestamp = kv[1];
            if (kv[0] == "h") headersList = kv[1];
            if (kv[0] == "v1") sigV1 = kv[1];
        }

        Request.EnableBuffering();
        string body;
        using (var reader = new StreamReader(Request.Body, leaveOpen:true))
            body = await reader.ReadToEndAsync();
        Request.Body.Position = 0;

        var headerNames = headersList.Split(' ');
        var headerValues = headerNames.Select(h => Request.Headers[h].ToString());
        var headerJoin = string.Join('.', headerValues);

        var signedPayload = $"{timestamp}.{headersList}.{headerJoin}.{body}";

        var expected = new HMACSHA256(System.Text.Encoding.UTF8.GetBytes(secret))
            .ComputeHash(System.Text.Encoding.UTF8.GetBytes(signedPayload));

        var expectedHex = Convert.ToHexString(expected).ToLower();

        if (!CryptographicOperations.FixedTimeEquals(
            System.Text.Encoding.UTF8.GetBytes(expectedHex),
            System.Text.Encoding.UTF8.GetBytes(sigV1)))
            return Unauthorized();

        return Ok();
    }
}

Node.js

const crypto = require("crypto");

function verifyHook0(req) {
  const sigHeader = req.headers["x-hook0-signature"];
  if (!sigHeader) return false;

  const parts = Object.fromEntries(
    sigHeader.split(",").map(p => p.split("="))
  );

  const timestamp = parts.t;
  const headersList = parts.h;
  const signature = parts.v1;

  const headerNames = headersList.split(" ");
  const headerValues = headerNames.map(h => req.headers[h.toLowerCase()]);
  const headerJoined = headerValues.join(".");

  const signedPayload =
    `${timestamp}.${headersList}.${headerJoined}.${req.rawBody}`;

  const expected = crypto
    .createHmac("sha256", process.env.HOOK0_SECRET)
    .update(signedPayload)
    .digest("hex");

  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signature)
  );
}

Python

import hmac
import hashlib

def verify_hook0(request, secret):
    sig_header = request.headers.get("X-Hook0-Signature")
    if not sig_header:
        return False

    parts = dict(p.split("=") for p in sig_header.split(","))

    timestamp = parts["t"]
    headers_list = parts["h"]
    signature = parts["v1"]

    header_names = headers_list.split(" ")
    header_values = [request.headers.get(h) for h in header_names]
    header_joined = ".".join(header_values)

    signed_payload = (
        f"{timestamp}.{headers_list}.{header_joined}."
        f"{request.data.decode()}"
    )

    expected = hmac.new(
        secret.encode(),
        signed_payload.encode(),
        hashlib.sha256
    ).hexdigest()

    return hmac.compare_digest(expected, signature)