Checking Webhook Signatures

    Verify the events that Stripe sends to your webhook endpoints.

    Stripe can optionally sign the webhook events it sends to your endpoints. We do so by including a signature in each event’s Stripe-Signature header. This allows you to verify that the events were sent by Stripe, not by a third party. You can verify signatures either using our official libraries, or manually using your own solution.

    Before you can verify signatures, you need to retrieve your endpoint’s secret from your Dashboard’s Webhooks settings. Select an endpoint that you want to obtain the secret for, then select the Click to reveal button.

    Each secret is unique to the endpoint to which it corresponds. If you use the same endpoint for both test and live API keys, note that the secret is different for each one. Additionally, if you use multiple endpoints, you must obtain a secret for each one. After this setup, Stripe starts to sign each webhook it sends to the endpoint.

    Verifying signatures using our official libraries

    We recommend using one of our official libraries to verify signatures. You perform the verification by providing the event payload, the Stripe-Signature header, and the endpoint’s secret. If verification fails, Stripe returns an error.

    # Set your secret key: remember to change this to your live secret key in production
    # See your keys here: https://dashboard.stripe.com/account/apikeys
    Stripe.api_key = 'sk_test_4eC39HqLyjWDarjtT1zdp7dc'
    
    # You can find your endpoint's secret in your webhook settings
    endpoint_secret = 'whsec_...'
    
    # Using Sinatra
    post '/my/webhook/url' do
        payload = request.body.read
        sig_header = request.env['HTTP_STRIPE_SIGNATURE']
        event = nil
    
        begin
            event = Stripe::Webhook.construct_event(
                payload, sig_header, endpoint_secret
            )
        rescue JSON::ParserError => e
            # Invalid payload
            status 400
            return
        rescue Stripe::SignatureVerificationError => e
            # Invalid signature
            status 400
            return
        end
    
        # Handle the event
        case event.type
        when 'payment_intent.succeeded'
          payment_intent = event.data.object # contains a Stripe::PaymentIntent
          handle_payment_intent_succeeded(payment_intent)
        when 'payment_method.attached'
          payment_method = event.data.object # contains a Stripe::PaymentMethod
          handle_payment_method_attached(payment_method)
        # ... handle other event types
        else
          # Unexpected event type
          status 400
          return
        end
    
        status 200
    end
    
    # Set your secret key: remember to change this to your live secret key in production
    # See your keys here: https://dashboard.stripe.com/account/apikeys
    stripe.api_key = 'sk_test_4eC39HqLyjWDarjtT1zdp7dc'
    
    from django.http import HttpResponse
    
    # You can find your endpoint's secret in your webhook settings
    endpoint_secret = 'whsec_...'
    
    # Using Django
    @csrf_exempt
    def my_webhook_view(request):
      payload = request.body
      sig_header = request.META['HTTP_STRIPE_SIGNATURE']
      event = None
    
      try:
        event = stripe.Webhook.construct_event(
          payload, sig_header, endpoint_secret
        )
      except ValueError as e:
        # Invalid payload
        return HttpResponse(status=400)
      except stripe.error.SignatureVerificationError as e:
        # Invalid signature
        return HttpResponse(status=400)
    
      # Handle the event
      if event.type == 'payment_intent.succeeded'
        payment_intent = event.data.object # contains a stripe.PaymentIntent
        handle_payment_intent_succeeded(payment_intent)
      elif event.type == 'payment_method.attached'
        payment_method = event.data.object # contains a stripe.PaymentMethod
        handle_payment_method_attached(payment_method)
      # ... handle other event types
      else
        # Unexpected event type
        return HttpResponse(status=400)
      end
    
      return HttpResponse(status=200)
    
    // Set your secret key: remember to change this to your live secret key in production
    // See your keys here: https://dashboard.stripe.com/account/apikeys
    \Stripe\Stripe::setApiKey('sk_test_4eC39HqLyjWDarjtT1zdp7dc');
    
    // You can find your endpoint's secret in your webhook settings
    $endpoint_secret = 'whsec_...';
    
    $payload = @file_get_contents('php://input');
    $sig_header = $_SERVER['HTTP_STRIPE_SIGNATURE'];
    $event = null;
    
    try {
        $event = \Stripe\Webhook::constructEvent(
            $payload, $sig_header, $endpoint_secret
        );
    } catch(\UnexpectedValueException $e) {
        // Invalid payload
        http_response_code(400);
        exit();
    } catch(\Stripe\Error\SignatureVerification $e) {
        // Invalid signature
        http_response_code(400);
        exit();
    }
    
    // Handle the event
    switch ($event->type) {
        case 'payment_intent.succeeded':
            $paymentIntent = $event->data->object; // contains a StripePaymentIntent
            handlePaymentIntentSucceeded($paymentIntent);
            break;
        case 'payment_method.attached':
            $paymentMethod = $event->data->object; // contains a StripePaymentMethod
            handlePaymentMethodAttached($paymentMethod);
            break;
        // ... handle other event types
        default:
            // Unexpected event type
            http_response_code(400);
            exit();
    }
    
    http_response_code(200);
    
    // Set your secret key: remember to change this to your live secret key in production
    // See your keys here: https://dashboard.stripe.com/account/apikeys
    Stripe.apiKey = "sk_test_4eC39HqLyjWDarjtT1zdp7dc";
    
    // You can find your endpoint's secret in your webhook settings
    String endpointSecret = "whsec_...";
    
    // Using the Spark framework (http://sparkjava.com)
    public Object handle(Request request, Response response) {
      String payload = request.body();
      String sigHeader = request.headers("Stripe-Signature");
      Event event = null;
    
      try {
        event = Webhook.constructEvent(
          payload, sigHeader, endpointSecret
        );
      } catch (JsonSyntaxException e) {
        // Invalid payload
        response.status(400);
        return "";
      } catch (SignatureVerificationException e) {
        // Invalid signature
        response.status(400);
        return "";
      }
    
      // Deserialize the nested object inside the event
      EventDataObjectDeserializer dataObjectDeserializer = event.getDataObjectDeserializer();
      StripeObject stripeObject = null;
      if (dataObjectDeserializer.getObject().isPresent()) {
        stripeObject = dataObjectDeserializer.getObject().get();
      } else {
        // Deserialization failed, probably due to an API version mismatch.
        // Refer to the Javadoc documentation on `EventDataObjectDeserializer` for
        // instructions on how to handle this case, or return an error here.
      }
    
      // Handle the event
      switch (event.getType()) {
        case "payment_intent.succeeded":
          PaymentIntent paymentIntent = (PaymentIntent) stripeObject;
          handlePaymentIntentSucceeded(paymentIntent);
          break;
        case "payment_method.attached":
          PaymentMethod paymentMethod = (PaymentMethod) stripeObject;
          handlePaymentMethodAttached(paymentMethod);
          break;
        // ... handle other event types
        default:
          // Unexpected event type
          response.status(400);
          return "";
      }
    
      response.status(200);
      return "";
    }
    
    // Set your secret key: remember to change this to your live secret key in production
    // See your keys here: https://dashboard.stripe.com/account/apikeys
    const stripe = require('stripe')('sk_test_4eC39HqLyjWDarjtT1zdp7dc');
    
    // Find your endpoint's secret in your Dashboard's webhook settings
    const endpointSecret = 'whsec_...';
    
    // This example uses Express to receive webhooks
    const app = require('express')();
    
    // Use body-parser to retrieve the raw body as a buffer
    const bodyParser = require('body-parser');
    
    // Match the raw body to content type application/json
    app.post('/webhook', bodyParser.raw({type: 'application/json'}), (request, response) => {
      const sig = request.headers['stripe-signature'];
    
      let event;
    
      try {
        event = stripe.webhooks.constructEvent(request.body, sig, endpointSecret);
      }
      catch (err) {
        response.status(400).send(`Webhook Error: ${err.message}`);
      }
    
      // Handle the event
      switch (event.type) {
        case 'payment_intent.succeeded':
          const paymentIntent = event.data.object;
          handlePaymentIntentSucceeded(paymentIntent);
          break;
        case 'payment_method.attached':
          const paymentMethod = event.data.object;
          handlePaymentMethodAttached(paymentMethod);
          break;
        // ... handle other event types
        default:
          // Unexpected event type
          return response.status(400).end();
      }
    
      // Return a response to acknowledge receipt of the event
      response.json({received: true});
    });
    
    app.listen(8000, () => console.log('Running on port 8000'));
    
    // Set your secret key: remember to change this to your live secret key in production
    // See your keys here: https://dashboard.stripe.com/account/apikeys
    stripe.Key = "sk_test_4eC39HqLyjWDarjtT1zdp7dc"
    
    http.HandleFunc("/webhook", func(w http.ResponseWriter, req *http.Request) {
        const MaxBodyBytes = int64(65536)
        req.Body = http.MaxBytesReader(w, req.Body, MaxBodyBytes)
        payload, err := ioutil.ReadAll(req.Body)
        if err != nil {
            fmt.Fprintf(os.Stderr, "Error reading request body: %v\n", err)
            w.WriteHeader(http.StatusServiceUnavailable)
            return
        }
    
        // Pass the request body and Stripe-Signature header to ConstructEvent, along
        // with the webhook signing key.
        // You can find your endpoint's secret in your webhook settings
        endpointSecret := "whsec_...";
        event, err := webhook.ConstructEvent(payload, req.Header.Get("Stripe-Signature"),
            endpointSecret)
    
        if err != nil {
            fmt.Fprintf(os.Stderr, "Error verifying webhook signature: %v\n", err)
            w.WriteHeader(http.StatusBadRequest) // Return a 400 error on a bad signature
            return
        }
    
        // Unmarshal the event data into an appropriate struct depending on its Type
        switch event.Type {
        case "payment_intent.succeeded":
            var paymentIntent stripe.PaymentIntent
            err := json.Unmarshal(event.Data.Raw, &paymentIntent)
            if err != nil {
                fmt.Fprintf(os.Stderr, "Error parsing webhook JSON: %v\n", err)
                w.WriteHeader(http.StatusBadRequest)
                return
            }
            handlePaymentIntentSucceeded(paymentIntent)
        case "payment_method.attached":
            var paymentMethod stripe.PaymentMethod
            err := json.Unmarshal(event.Data.Raw, &paymentMethod)
            if err != nil {
                fmt.Fprintf(os.Stderr, "Error parsing webhook JSON: %v\n", err)
                w.WriteHeader(http.StatusBadRequest)
                return
            }
            handlePaymentMethodAttached(paymentMethod)
        // ... handle other event types
        default:
            fmt.Fprintf(os.Stderr, "Unexpected event type: %s\n", event.Type)
            w.WriteHeader(http.StatusBadRequest)
            return
        }
    
        w.WriteHeader(http.StatusOK)
    })
    
    // Set your secret key: remember to change this to your live secret key in production
    // See your keys here: https://dashboard.stripe.com/account/apikeys
    StripeConfiguration.ApiKey = "sk_test_4eC39HqLyjWDarjtT1zdp7dc";
    
    using System;
    using System.IO;
    using Microsoft.AspNetCore.Mvc;
    using Stripe;
    
    namespace workspace.Controllers
    {
        [Route("api/[controller]")]
        public class StripeWebHook : Controller
        {
            // You can find your endpoint's secret in your webhook settings
            const string secret = "whsec_...";
    
            [HttpPost]
            public void Index()
            {
                var json = new StreamReader(HttpContext.Request.Body).ReadToEnd();
    
                try
                {
                    var stripeEvent = EventUtility.ConstructEvent(json,
                        Request.Headers["Stripe-Signature"], secret);
    
                    // Handle the event
                    if (stripeEvent.Type == Events.PaymentIntentSucceeded)
                    {
                        var paymentIntent = stripeEvent.Data.Object as PaymentIntent;
                        handlePaymentIntentSucceeded(paymentIntent);
                    }
                    else if (stripeEvent.Type == Events.PaymentMethodAttached)
                    {
                        var paymentMethod = stripeEvent.Data.Object as PaymentMethod;
                        handlePaymentMethodAttached(paymentMethod);
                    }
                    // ... handle other event types
                    else
                    {
                        // Unexpected event type
                        return BadRequest();
                    }
    
                }
                catch (StripeException e)
                {
                    return BadRequest();
                }
            }
        }
    }
    

    Preventing replay attacks

    A replay attack is when an attacker intercepts a valid payload and its signature, then re-transmits them. To mitigate such attacks, Stripe includes a timestamp in the Stripe-Signature header. Because this timestamp is part of the signed payload, it is also verified by the signature, so an attacker cannot change the timestamp without invalidating the signature. If the signature is valid but the timestamp is too old, you can have your application reject the payload.

    Our libraries have a default tolerance of five minutes between the timestamp and the current time. You can change this tolerance by providing an additional parameter when verifying signatures. We recommend that you use Network Time Protocol (NTP) to ensure that your server’s clock is accurate and synchronizes with the time on Stripe’s servers.

    Stripe generates the timestamp and signature each time we send an event to your endpoint. If Stripe retries an event (e.g., your endpoint previously replied with a non-2xx status code), then we generate a new signature and timestamp for the new delivery attempt.

    Verifying signatures manually

    Although we recommend using our official libraries to verify webhook event signatures, you can use the following information to create a custom solution.

    The Stripe-Signature header contains a timestamp and one or more signatures. The timestamp is prefixed by t=, and each signature is prefixed by a scheme. Schemes start with v, followed by an integer. Currently, the only valid signature scheme is v1. To aid with testing, Stripe sends an additional signature with a fake v0 scheme, for test-mode events.

    Stripe-Signature: t=1492774577,
        v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd,
        v0=6ffbb59b2300aae63f272406069a9788598b792a944a07aba816edb039989a39
    

    Note that newlines have been added in the example above for clarity, but a real Stripe-Signature header will be all one line.

    Stripe generates signatures using a hash-based message authentication code (HMAC) with SHA-256. To prevent downgrade attacks, you should ignore all schemes that are not v1.

    It is possible to have multiple signatures with the same scheme/secret pair. This can happen when you roll an endpoint’s secret from the Dashboard, and choose to keep the previous secret active for up to 24 hours. During this time, your endpoint has multiple active secrets and Stripe generates one signature for each secret.

    Step 1: Extract the timestamp and signatures from the header

    Split the header, using the , character as the separator, to get a list of elements. Then split each element, using the = character as the separator, to get a prefix and value pair.

    The value for the prefix t corresponds to the timestamp, and v1 corresponds to the signature(s). You can discard all other elements.

    Step 2: Prepare the signed_payload string

    You achieve this by concatenating:

    • The timestamp (as a string)
    • The character .
    • The actual JSON payload (i.e., the request’s body)

    Step 3: Determine the expected signature

    Compute an HMAC with the SHA256 hash function. Use the endpoint’s signing secret as the key, and use the signed_payload string as the message.

    Step 4: Compare signatures

    Compare the signature(s) in the header to the expected signature. If a signature matches, compute the difference between the current timestamp and the received timestamp, then decide if the difference is within your tolerance.

    To protect against timing attacks, use a constant-time string comparison to compare the expected signature to each of the received signatures.

    More information

    Was this page helpful?

    Thank you for helping improve Stripe's documentation. If you need help or have any questions, please consider contacting support.

    Questions?

    We're always happy to help with code or other questions you might have. Search our documentation, contact support, or connect with our sales team. You can also chat live with other developers in #stripe on freenode.

    On this page