Webhooks

Swell signs every webhook with HMAC-SHA512. Verify the signature before trusting the payload — this protects against spoofed events.

Headers

Swell-Signature: t=<unix>,v1=<hex>
Swell-Event: event type (e.g. payment.completed)
Swell-Event-Id: unique event id for idempotency

Verify — Node.js

verify.js
const crypto = require('crypto');

function verify(secret, rawBody, header, tolerance = 300) {
  const parts = Object.fromEntries(
    header.split(',').map((kv) => kv.split('='))
  );
  const t = Number(parts.t);
  const v1 = parts.v1;
  if (!t || !v1) return false;
  if (Math.abs(Date.now() / 1000 - t) > tolerance) return false;

  const expected = crypto
    .createHmac('sha512', secret)
    .update(`${t}.${rawBody}`)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(expected, 'hex'),
    Buffer.from(v1, 'hex')
  );
}

Verify — PHP

verify.php
function verify_swell(string $secret, string $payload, string $header): bool {
  $parts = [];
  foreach (explode(',', $header) as $kv) {
    [$k, $v] = explode('=', trim($kv), 2);
    $parts[$k] = $v;
  }
  $t = (int)($parts['t'] ?? 0);
  $v1 = $parts['v1'] ?? '';
  if (!$t || !$v1) return false;
  if (abs(time() - $t) > 300) return false;

  $expected = hash_hmac('sha512', "$t.$payload", $secret);
  return hash_equals($expected, $v1);
}

Verify — Python

verify.py
import hmac, hashlib, time

def verify(secret: str, payload: str, header: str, tolerance: int = 300) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    t, v1 = int(parts.get("t", 0)), parts.get("v1", "")
    if not t or not v1:
        return False
    if abs(int(time.time()) - t) > tolerance:
        return False
    expected = hmac.new(
        secret.encode(), f"{t}.{payload}".encode(), hashlib.sha512
    ).hexdigest()
    return hmac.compare_digest(expected, v1)

Verify — Go

verify.go
func Verify(secret, payload, header string) bool {
  parts := map[string]string{}
  for _, kv := range strings.Split(header, ",") {
    p := strings.SplitN(strings.TrimSpace(kv), "=", 2)
    if len(p) == 2 { parts[p[0]] = p[1] }
  }
  t, _ := strconv.ParseInt(parts["t"], 10, 64)
  v1 := parts["v1"]
  if t == 0 || v1 == "" { return false }
  if abs(time.Now().Unix()-t) > 300 { return false }

  mac := hmac.New(sha512.New, []byte(secret))
  mac.Write([]byte(fmt.Sprintf("%d.%s", t, payload)))
  expected := hex.EncodeToString(mac.Sum(nil))
  return hmac.Equal([]byte(expected), []byte(v1))
}

Verify — Rust

verify.rs
use hmac::{Hmac, Mac};
use sha2::Sha512;

type HmacSha512 = Hmac<Sha512>;

fn verify(secret: &str, payload: &str, header: &str) -> bool {
    let mut t = 0u64;
    let mut v1 = String::new();
    for part in header.split(',') {
        let mut kv = part.trim().splitn(2, '=');
        match (kv.next(), kv.next()) {
            (Some("t"), Some(v)) => t = v.parse().unwrap_or(0),
            (Some("v1"), Some(v)) => v1 = v.to_string(),
            _ => {}
        }
    }
    let mut mac = HmacSha512::new_from_slice(secret.as_bytes()).unwrap();
    mac.update(format!("{t}.{payload}").as_bytes());
    let expected = hex::encode(mac.finalize().into_bytes());
    expected == v1
}

Verify — C#

Verify.cs
static bool Verify(string secret, string payload, string header)
{
    var parts = header.Split(',')
        .Select(p => p.Trim().Split('=', 2))
        .ToDictionary(p => p[0], p => p[1]);
    if (!parts.TryGetValue("t", out var tStr) ||
        !parts.TryGetValue("v1", out var v1)) return false;
    var t = long.Parse(tStr);
    if (Math.Abs(DateTimeOffset.UtcNow.ToUnixTimeSeconds() - t) > 300)
        return false;

    using var hmac = new HMACSHA512(Encoding.UTF8.GetBytes(secret));
    var hash = hmac.ComputeHash(Encoding.UTF8.GetBytes($"{t}.{payload}"));
    var expected = Convert.ToHexString(hash).ToLowerInvariant();
    return CryptographicOperations.FixedTimeEquals(
        Encoding.UTF8.GetBytes(expected),
        Encoding.UTF8.GetBytes(v1));
}

Events

checkout.created · checkout.completed · checkout.failed · checkout.expired · payment.authorized · payment.completed · payment.failed · refund.created · refund.completed · payout.created · payout.completed · customer.created · customer.updated · invoice.created · subscription.created · subscription.cancelled