StripeKit: Webhooks

Searching...

No Matches

Webhooks, are HTTP requests made by Stripe to our server to notify us of events (e.g., payment success). More...

Collaboration diagram for Webhooks:

Classes
struct	stripekit::VerifiedEventSignal
	A verified event, with the delivery details that came with it. More...
class	stripekit::EventDispatcher
	Handles verified webhook events, for applications using WebhookProcessor. More...
class	stripekit::SqliteWebhookDedupStore
	A de-duplication store that uses a SQLite database. More...
struct	stripekit::ClaimRequest
	Asks the store to reserve an event id. More...
struct	stripekit::ClaimResult
	The store's answer to a ClaimRequest. More...
class	stripekit::WebhookDedupStore
	Remembers which webhook events have been handled. More...
class	stripekit::InMemoryWebhookDedupStore
	A de-duplication store that keeps everything in memory. More...
struct	stripekit::WebhookProcessorOptions
	Tuning for WebhookProcessor. More...
class	stripekit::WebhookProcessor
	Handles incoming webhook deliveries through an EventDispatcher. More...
struct	stripekit::WebhookVerificationInput
	Everything needed to check a webhook signature. More...
struct	stripekit::VerificationMetadata
	What was learned from a signature that checked out. More...
class	stripekit::WebhookSignatureVerifier
	Checks that a webhook delivery really came from Stripe. More...
class	stripekit::DefaultWebhookSignatureVerifier
	The signature verifier StripeKit uses by default. More...
struct	stripekit::webhooks::ConstructEventOptions
	Tuning for construct_event(). More...
struct	stripekit::webhooks::ProcessEventOptions
	Tuning for process_event_once(). More...
struct	stripekit::webhooks::ProcessEventOnceResult
	What happened to a webhook delivery. More...

Typedefs
using	stripekit::webhooks::Event = EventEnvelope
	A verified Stripe webhook event.
using	stripekit::webhooks::ProcessResult = EventDispatchResult
	What a handler reports back about an event.
using	stripekit::webhooks::EventHandler = std::function<Task<ProcessResult>(const Event&)>
	The application's webhook handler.

Enumerations
enum class	stripekit::EventDispatchResult { stripekit::EventDispatchResult::Handled , stripekit::EventDispatchResult::Ignored , stripekit::EventDispatchResult::RetryableFailure , stripekit::EventDispatchResult::FatalFailure }
	What a webhook handler reports back about an event. More...
enum class	stripekit::ClaimOutcome { stripekit::ClaimOutcome::Claimed , stripekit::ClaimOutcome::DuplicateProcessed , stripekit::ClaimOutcome::DuplicateInflight , stripekit::ClaimOutcome::RetryableStoreError , stripekit::ClaimOutcome::FatalStoreError }
	The result of trying to reserve an event for processing. More...
enum class	stripekit::WebhookResponseAction { stripekit::WebhookResponseAction::AcknowledgeSuccess , stripekit::WebhookResponseAction::RetryLater }
	What to tell Stripe about a delivery. More...

Functions
bool	stripekit::sqlite_dedup_store_is_available ()
	Reports whether this build can use SqliteWebhookDedupStore.
WebhookResponseAction	stripekit::map_claim_outcome_to_response (ClaimOutcome outcome)
	Works out what to tell Stripe, given a claim outcome.
Event	stripekit::webhooks::construct_event (std::string_view payload, std::string_view signature_header, std::string_view endpoint_secret, ConstructEventOptions options={})
	Checks that a webhook delivery really came from Stripe, and parses it.
Task< ProcessEventOnceResult >	stripekit::webhooks::process_event_once (const Event &event, WebhookDedupStore &dedup_store, EventHandler handler, ProcessEventOptions options={})
	Runs the handler for an already-verified event unless it was already completed.
Task< ProcessEventOnceResult >	stripekit::webhooks::process_event_once (std::string_view payload, std::string_view signature_header, std::string_view endpoint_secret, WebhookDedupStore &dedup_store, EventHandler handler, ProcessEventOptions options={})
	Verifies a webhook delivery and handles it unless it was already completed.

Variables
constexpr std::chrono::minutes	stripekit::defaultStaleInflightTimeout { 15 }
	How long an unfinished claim is honoured before another process may take it.

Detailed Description

Webhooks, are HTTP requests made by Stripe to our server to notify us of events (e.g., payment success).

Stripe can deliver the same event more than once whenever it cannot confirm that you received it, so a webhook handler must be safe to run twice. The types here do that for you: they check the signature, reserve the event id in a store, and only then call your handler.

See also: https://docs.stripe.com/webhooks

Typedef Documentation

◆ Event

using stripekit::webhooks::Event = EventEnvelope

A verified Stripe webhook event.

Definition at line 31 of file Webhooks.h.

◆ ProcessResult

using stripekit::webhooks::ProcessResult = EventDispatchResult

What a handler reports back about an event.

Shared with EventDispatcher.

Definition at line 49 of file Webhooks.h.

◆ EventHandler

using stripekit::webhooks::EventHandler = std::function<Task<ProcessResult>(const Event&)>

The application's webhook handler.

Called after the signature has been checked and the event id claimed. Completed events are skipped; failed or interrupted attempts may run again. Make the handler safe to retry. Return quickly: Stripe treats a slow endpoint as a failed delivery, so queue any long work rather than doing it here.

Definition at line 59 of file Webhooks.h.

Enumeration Type Documentation

◆ EventDispatchResult

enum class stripekit::EventDispatchResult

strong

What a webhook handler reports back about an event.

Used by EventDispatcher and, as stripekit::webhooks::ProcessResult, by coroutine handlers.

Enumerator
Handled	Dealt with. Stripe is told the delivery succeeded.
Ignored	Not interesting to this application. Also reported as success.
RetryableFailure	Something was temporarily unavailable. Stripe will deliver again.
FatalFailure	Needs intervention. Logged as an error; Stripe is asked to retry.

Definition at line 30 of file Events.h.

◆ ClaimOutcome

enum class stripekit::ClaimOutcome

strong

The result of trying to reserve an event for processing.

Enumerator
Claimed	This worker reserved the event id and should process it now.
DuplicateProcessed	A previous delivery already completed processing.
DuplicateInflight	Another worker is already processing the same event.
RetryableStoreError	The store failed temporarily and the caller should retry.
FatalStoreError	The store failed in a non-recoverable way.

Definition at line 32 of file WebhookDedupStore.h.

◆ WebhookResponseAction

enum class stripekit::WebhookResponseAction

strong

What to tell Stripe about a delivery.

Enumerator

Enumerator
AcknowledgeSuccess	Answer 2xx. Stripe stops retrying this event.
RetryLater	Answer 5xx. Stripe delivers the event again later.

AcknowledgeSuccess

Answer 2xx.

Stripe stops retrying this event.

RetryLater

Answer 5xx.

Stripe delivers the event again later.

Definition at line 43 of file WebhookDedupStore.h.

Function Documentation

◆ sqlite_dedup_store_is_available()

bool stripekit::sqlite_dedup_store_is_available ( )

Reports whether this build can use SqliteWebhookDedupStore.

SQLite support is a build option, so a StripeKit built without it will fail to construct the store.

Returns: True when SQLite support was compiled in.

◆ map_claim_outcome_to_response()

WebhookResponseAction stripekit::map_claim_outcome_to_response ( ClaimOutcome outcome )

Works out what to tell Stripe, given a claim outcome.

Already-processed duplicates count as success. In-flight duplicates and store failures ask Stripe to retry.

Parameters

outcome The result of a claim attempt.

Returns: WebhookResponseAction::AcknowledgeSuccess for a claim or processed duplicate; WebhookResponseAction::RetryLater otherwise.

◆ construct_event()

Event stripekit::webhooks::construct_event	(	std::string_view	payload,
		std::string_view	signature_header,
		std::string_view	endpoint_secret,
		ConstructEventOptions	options = {} )

Checks that a webhook delivery really came from Stripe, and parses it.

Pass the request body exactly as received. The signature covers those precise bytes, so anything that re-encodes or reformats the body first will cause verification to fail.

This verifies but does not de-duplicate. Stripe delivers the same event more than once, so a handler that changes state should use process_event_once() instead.

const auto event = stripekit::webhooks::construct_event(

request_body, request.header("stripe-signature"), endpoint_secret);

stripekit::webhooks::construct_event

Event construct_event(std::string_view payload, std::string_view signature_header, std::string_view endpoint_secret, ConstructEventOptions options={})

Checks that a webhook delivery really came from Stripe, and parses it.

Parameters

payload	Raw request body, unmodified.
signature_header	Value of the "Stripe-Signature" header.
endpoint_secret	Signing secret for this endpoint, of the form "whsec_...". It differs between the Stripe CLI and each registered endpoint.
options	Timestamp tolerance and current time.

Returns: The verified event.

Exceptions

SignatureVerificationException	The signature does not match, or its timestamp is outside the tolerance. Answer the request with HTTP 400.
ConfigurationException	The payload is not a usable Stripe event.

See also: https://docs.stripe.com/webhooks#verify-events

◆ process_event_once() [1/2]

Task< ProcessEventOnceResult > stripekit::webhooks::process_event_once	(	const Event &	event,
		WebhookDedupStore &	dedup_store,
		EventHandler	handler,
		ProcessEventOptions	options = {} )

Runs the handler for an already-verified event unless it was already completed.

Reserves the event id in dedup_store first, so repeated deliveries of the same completed event are skipped while its record is retained. Failed attempts release their claims for retry; crashed attempts wait for the stale timeout. Use this overload when the event has already been through construct_event().

Parameters

event	The verified event.
dedup_store	Where claims are recorded. Must outlive the call, and must be shared by every process that handles this endpoint.
handler	Called only for the delivery that wins the claim.
options	Claim timing and logging.

Returns: What happened, including the status to send Stripe.

◆ process_event_once() [2/2]

Task< ProcessEventOnceResult > stripekit::webhooks::process_event_once	(	std::string_view	payload,
		std::string_view	signature_header,
		std::string_view	endpoint_secret,
		WebhookDedupStore &	dedup_store,
		EventHandler	handler,
		ProcessEventOptions	options = {} )

Verifies a webhook delivery and handles it unless it was already completed.

This is the whole inbound path in one call: check the signature, reserve the event id, run the handler, and report the status to send back to Stripe. It is what an adapter's webhook route should call.

auto result = co_await stripekit::webhooks::process_event_once(
    body, signature_header, endpoint_secret, dedup_store,
    [](const stripekit::webhooks::Event& event)
        -> stripekit::Task<stripekit::webhooks::ProcessResult> {
        co_return stripekit::webhooks::ProcessResult::Handled;
    });

Parameters

payload	Raw request body, unmodified.
signature_header	Value of the "Stripe-Signature" header.
endpoint_secret	Signing secret for this endpoint.
dedup_store	Where claims are recorded. Must outlive the call.
handler	Called only for the delivery that wins the claim.
options	Tolerance, claim timing, and logging.

Returns: What happened, including the status to send Stripe.

Exceptions

SignatureVerificationException	The delivery cannot be trusted. Answer with HTTP 400 rather than retrying.
ConfigurationException	The payload is not a usable Stripe event.

Variable Documentation

◆ defaultStaleInflightTimeout

std::chrono::minutes stripekit::defaultStaleInflightTimeout { 15 }

inlineconstexpr

How long an unfinished claim is honoured before another process may take it.

Definition at line 27 of file WebhookDedupStore.h.

Classes

Typedefs

Enumerations

Functions

Variables

Detailed Description

Typedef Documentation

◆ Event

◆ ProcessResult

◆ EventHandler

Enumeration Type Documentation

◆ EventDispatchResult

◆ ClaimOutcome

◆ WebhookResponseAction

Function Documentation

◆ sqlite_dedup_store_is_available()

◆ map_claim_outcome_to_response()

◆ construct_event()

◆ process_event_once() [1/2]

◆ process_event_once() [2/2]

Variable Documentation

◆ defaultStaleInflightTimeout