webhook.hpp

Go to the documentation of this file.

// §13 Webhook signature verification (T-145).
//
// AXIAM signs every webhook delivery with a Stripe-style signed timestamp:
//
//   X-Axiam-Timestamp : <unix seconds, decimal ASCII>
//   X-Axiam-Signature : t=<unix seconds>,v1=<hex lowercase HMAC-SHA256>
//   X-Axiam-Event     : <event type>
//   X-Axiam-Delivery  : <delivery UUID>
//
// where `v1 = HMAC-SHA256(secret_utf8_bytes, "<t>.<raw_body>")`.
//
// !! The body MUST be the exact raw bytes received off the wire. !!
// Never re-serialize parsed JSON before verifying — a change in key order or
// whitespace changes the MAC and the signature will not match. Capture the body
// before your framework's JSON parser touches it.
//
// Dedup is the receiver's job: `X-Axiam-Delivery` is the at-least-once dedup
// key. A retry replays a byte-identical, still-valid signature inside the
// freshness window, so keep a short-lived seen-set of delivery ids if your
// handler is not idempotent.
#pragma once
 
#include <chrono>
#include <cstdint>
#include <functional>
#include <optional>
#include <string>
 
#include "axiam/errors.hpp"
#include "axiam/sensitive.hpp"
 
namespace axiam {
namespace webhook {
 
enum class VerifyError {
    kNone = 0,
    kEmptySecret,             
    kMalformedHeader,         
    kMissingSignature,        
    kMalformedTimestamp,      
    kTimestampHeaderMismatch, 
    kSignatureMismatch,       
    kTimestampOutOfTolerance, 
};
 
const char* to_string(VerifyError error) noexcept;
 
struct Event {
    std::int64_t timestamp = 0;
    std::string event_type;
    std::string delivery_id;
    std::string body;
};
 
struct Options {
    std::chrono::seconds tolerance{300};
 
    std::function<std::int64_t()> now;
 
    std::optional<std::string> timestamp_header;
 
    std::string event_type;
 
    std::string delivery_id;
};
 
struct Result {
    bool ok = false;
    VerifyError error = VerifyError::kNone;
    Event event;
 
    explicit operator bool() const noexcept { return ok; }
    const char* error_message() const noexcept { return to_string(error); }
};
 
class VerifyException : public AxiamError {
public:
    VerifyException(VerifyError error, const std::string& message)
        : AxiamError(message), error_(error) {}
    VerifyError error() const noexcept { return error_; }
 
private:
    VerifyError error_;
};
 
Result verify(const Sensitive<std::string>& secret, const std::string& signature_header,
              const std::string& body, const Options& options = Options{});
 
Result verify(const std::string& secret, const std::string& signature_header,
              const std::string& body, const Options& options = Options{});
 
Event verify_or_throw(const Sensitive<std::string>& secret, const std::string& signature_header,
                      const std::string& body, const Options& options = Options{});
 
}  // namespace webhook
}  // namespace axiam