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