webhook

Documentation

Overview

Example

package main

import (
	"fmt"
	"io/ioutil"
	"log"
	"net/http"

	"github.com/stripe/stripe-go/v76/webhook"
)

func main() {
	http.HandleFunc("/webhook", func(w http.ResponseWriter, req *http.Request) {
		// Protects against a malicious client streaming us an endless request
		// body
		const MaxBodyBytes = int64(65536)
		req.Body = http.MaxBytesReader(w, req.Body, MaxBodyBytes)

		body, err := ioutil.ReadAll(req.Body)
		if err != nil {
			w.WriteHeader(http.StatusBadRequest)
			return
		}

		// Pass the request body & Stripe-Signature header to ConstructEvent, along with the webhook signing key
		event, err := webhook.ConstructEvent(body, req.Header.Get("Stripe-Signature"), "whsec_DaLRHCRs35vEXqOE8uTEAXGLGUOnyaFf")

		if err != nil {
			w.WriteHeader(http.StatusBadRequest) // Return a 400 error on a bad signature
			fmt.Fprintf(w, "%v", err)
			return
		}

		fmt.Fprintf(w, "Received signed event: %v", event)
	})
	log.Fatal(http.ListenAndServe(":8080", nil))
}

Index

• Constants
• Variables
• func ComputeSignature(t time.Time, payload []byte, secret string) []byte
• func ConstructEvent(payload []byte, header string, secret string) (stripe.Event, error)
• func ConstructEventIgnoringTolerance(payload []byte, header string, secret string) (stripe.Event, error)
• func ConstructEventWithOptions(payload []byte, header string, secret string, options ConstructEventOptions) (stripe.Event, error)
• func ConstructEventWithTolerance(payload []byte, header string, secret string, tolerance time.Duration) (stripe.Event, error)
• func ValidatePayload(payload []byte, header string, secret string) error
• func ValidatePayloadIgnoringTolerance(payload []byte, header string, secret string) error
• func ValidatePayloadWithTolerance(payload []byte, header string, secret string, tolerance time.Duration) error
• type ConstructEventOptions
• type SignedPayload
  • func GenerateTestSignedPayload(options *UnsignedPayload) *SignedPayload
• type UnsignedPayload

Examples

• Package

Constants

const (
	// DefaultTolerance indicates that signatures older than this will be rejected by ConstructEvent.
	DefaultTolerance time.Duration = 300 * time.Second
)

Variables

var (
	ErrInvalidHeader    = errors.New("webhook has invalid Stripe-Signature header")
	ErrNoValidSignature = errors.New("webhook had no valid signature")
	ErrNotSigned        = errors.New("webhook has no Stripe-Signature header")
	ErrTooOld           = errors.New("timestamp wasn't within tolerance")
)

This block represents the list of errors that could be raised when using the webhook package.

Functions

func ComputeSignature

func ComputeSignature(t time.Time, payload []byte, secret string) []byte

ComputeSignature computes a webhook signature using Stripe's v1 signing method.

See https://stripe.com/docs/webhooks#signatures for more information.

func ConstructEvent

func ConstructEvent(payload []byte, header string, secret string) (stripe.Event, error)

ConstructEvent initializes an Event object from a JSON webhook payload, validating the Stripe-Signature header using the specified signing secret. Returns an error if the body or Stripe-Signature header provided are unreadable, if the signature doesn't match, or if the timestamp for the signature is older than DefaultTolerance.

NOTE: Stripe will only send Webhook signing headers after you have retrieved your signing secret from the Stripe dashboard: https://dashboard.stripe.com/webhooks

This will return an error if the event API version does not match the stripe.APIVersion constant.

func ConstructEventIgnoringTolerance

func ConstructEventIgnoringTolerance(payload []byte, header string, secret string) (stripe.Event, error)

ConstructEventIgnoringTolerance initializes an Event object from a JSON webhook payload, validating the Stripe-Signature header using the specified signing secret. Returns an error if the body or Stripe-Signature header provided are unreadable or if the signature doesn't match. Does not check the signature's timestamp.

NOTE: Stripe will only send Webhook signing headers after you have retrieved your signing secret from the Stripe dashboard: https://dashboard.stripe.com/webhooks

This will return an error if the event API version does not match the stripe.APIVersion constant.

func ConstructEventWithOptions

func ConstructEventWithOptions(payload []byte, header string, secret string, options ConstructEventOptions) (stripe.Event, error)

ConstructEventWithOptions initializes an Event object from a JSON webhook payload, validating the signature in the Stripe-Signature header using the specified signing secret and tolerance window provided by the options, if applicable.

See `ConstructEventOptions` for more details on each of the options.

Returns an error if the signature doesn't match, or:

• if `IgnoreTolerance` is false and the timestamp embedded in the event header is not within the tolerance window (similar to `ConstructEventWithTolerance`)
• if `IgnoreAPIVersionMismatch` is false and the webhook event API version does not match the API version of the stripe-go library, as defined in `stripe.APIVersion`.

NOTE: Stripe will only send Webhook signing headers after you have retrieved your signing secret from the Stripe dashboard: https://dashboard.stripe.com/webhooks

func ConstructEventWithTolerance

func ConstructEventWithTolerance(payload []byte, header string, secret string, tolerance time.Duration) (stripe.Event, error)

ConstructEventWithTolerance initializes an Event object from a JSON webhook payload, validating the signature in the Stripe-Signature header using the specified signing secret and tolerance window. Returns an error if the body or Stripe-Signature header provided are unreadable, if the signature doesn't match, or if the timestamp for the signature is older than the specified tolerance.

NOTE: Stripe will only send Webhook signing headers after you have retrieved your signing secret from the Stripe dashboard: https://dashboard.stripe.com/webhooks

This will return an error if the event API version does not match the stripe.APIVersion constant.

func ValidatePayload

func ValidatePayload(payload []byte, header string, secret string) error

ValidatePayload validates the payload against the Stripe-Signature header using the specified signing secret. Returns an error if the body or Stripe-Signature header provided are unreadable, if the signature doesn't match, or if the timestamp for the signature is older than DefaultTolerance.

NOTE: Stripe will only send Webhook signing headers after you have retrieved your signing secret from the Stripe dashboard: https://dashboard.stripe.com/webhooks

func ValidatePayloadIgnoringTolerance

func ValidatePayloadIgnoringTolerance(payload []byte, header string, secret string) error

ValidatePayloadIgnoringTolerance validates the payload against the Stripe-Signature header using the specified signing secret. Returns an error if the body or Stripe-Signature header provided are unreadable or if the signature doesn't match. Does not check the signature's timestamp.

NOTE: Stripe will only send Webhook signing headers after you have retrieved your signing secret from the Stripe dashboard: https://dashboard.stripe.com/webhooks

func ValidatePayloadWithTolerance

func ValidatePayloadWithTolerance(payload []byte, header string, secret string, tolerance time.Duration) error

ValidatePayloadWithTolerance validates the payload against the Stripe-Signature header using the specified signing secret and tolerance window. Returns an error if the body or Stripe-Signature header provided are unreadable, if the signature doesn't match, or if the timestamp for the signature is older than the specified tolerance.

NOTE: Stripe will only send Webhook signing headers after you have retrieved your signing secret from the Stripe dashboard: https://dashboard.stripe.com/webhooks

Types

type ConstructEventOptions

type ConstructEventOptions struct {
	// Validates event timestamps using a custom Tolerance window. If this is
	// not set and `IgnoreTolerance` is false, will default to
	// `DefaultTolerance`.
	Tolerance time.Duration

	// If set to true, will ignore the `tolerance` option entirely and will not
	// check the event signature's timestamp. Defaults to false. When false,
	// constructing an event will fail with an error if the timestamp is not
	// within the `Tolerance` window.
	IgnoreTolerance bool

	// If set to true, will ignore validating whether an event's API version
	// matches the stripe-go API version. Defaults to false, returning an error
	// when there is a mismatch.
	IgnoreAPIVersionMismatch bool
}

type SignedPayload

type SignedPayload struct {
	UnsignedPayload

	Signature []byte
	Header    string
}

func GenerateTestSignedPayload

func GenerateTestSignedPayload(options *UnsignedPayload) *SignedPayload

type UnsignedPayload

type UnsignedPayload struct {
	Payload   []byte
	Secret    string
	Timestamp time.Time
	Scheme    string
}

For mocking webhook events