REST API

BoxCart exposes a WordPress REST API endpoint for Stripe webhook processing, providing real-time payment status updates for your orders.

Overview

BoxCart currently exposes one REST API endpoint dedicated to Stripe webhook processing. The endpoint is registered by the BoxCart_Webhook class, which hooks into the rest_api_init action during WordPress initialisation.

The REST API is used as a callback URL for Stripe to notify your site about payment events in real time. This serves as a reliable backup to the synchronous PaymentIntent status check that runs when a customer is redirected back to your site after payment.

add_action( 'rest_api_init', array( $this, 'register_routes' ) );

register_rest_route(
    'boxcart/v1',
    '/webhook/stripe',
    array(
        'methods'             => 'POST',
        'callback'            => array( $this, 'handle_stripe_webhook' ),
        'permission_callback' => '__return_true',
    )
);

Stripe Webhook Endpoint

The full URL for your site will be:

https://yoursite.com/wp-json/boxcart/v1/webhook/stripe

This URL is also displayed as a read-only field in BoxCart → Settings → Payments when Stripe is enabled, so you can copy it directly from there.

Authentication

The webhook endpoint does not use WordPress authentication. Instead, it relies on Stripe signature verification using HMAC-SHA256 to ensure that incoming requests genuinely originate from Stripe.

When Stripe sends a webhook event, it includes a Stripe-Signature header containing a timestamp and one or more signatures. BoxCart verifies these by:

1. Parsing the Stripe-Signature header to extract the timestamp (t) and signature(s) (v1).
2. Checking that the timestamp is within a 5-minute tolerance window to prevent replay attacks.
3. Constructing the signed payload as {timestamp}.{raw_body}.
4. Computing the expected signature using hash_hmac('sha256', $signed_payload, $webhook_secret).
5. Comparing the expected signature against the provided signature(s) using hash_equals() for timing-safe comparison.

Supported Events

The webhook handler processes two Stripe event types. All other event types are acknowledged with a 200 response but no action is taken.

Both events use the order_id stored in the PaymentIntent's metadata to look up the corresponding BoxCart order. If the order_id is missing from the metadata or the order cannot be found, the event is logged and skipped.

public function handle_webhook_event( $event ) {
    $type = isset( $event['type'] ) ? $event['type'] : '';
    $data = isset( $event['data']['object'] ) ? $event['data']['object'] : array();

    switch ( $type ) {
        case 'payment_intent.succeeded':
            return $this->handle_payment_succeeded( $data );

        case 'payment_intent.payment_failed':
            return $this->handle_payment_failed( $data );

        default:
            // Unhandled event type — acknowledge receipt.
            return true;
    }
}

Setting Up Webhooks

Follow these steps to configure Stripe webhooks for your BoxCart store.

1. Open the Stripe Dashboard

   Log in to your Stripe Dashboard and navigate to Developers → Webhooks.

2. Add a new endpoint

   Click Add endpoint. In the Endpoint URL field, enter your BoxCart webhook URL:

   https://yoursite.com/wp-json/boxcart/v1/webhook/stripe

   Replace yoursite.com with your actual domain.

3. Select events to listen for

   Click Select events and choose the following two events:

   • payment_intent.succeeded
   • payment_intent.payment_failed

   Click Add events, then Add endpoint to save.

4. Copy the signing secret

   After creating the endpoint, Stripe will display a Signing secret that begins with whsec_. Click to reveal and copy this value.

5. Paste the secret into BoxCart

   In your WordPress admin, go to BoxCart → Settings → Payments. Paste the signing secret into the Webhook Secret field and save your settings.

Request Format

Stripe sends webhook events as POST requests with a JSON body. The request includes a Stripe-Signature header used for verification.

POST /wp-json/boxcart/v1/webhook/stripe HTTP/1.1
Host: yoursite.com
Content-Type: application/json
Stripe-Signature: t=1681000000,v1=abc123def456...

{
  "id": "evt_1abc123",
  "type": "payment_intent.succeeded",
  "data": {
    "object": {
      "id": "pi_1xyz789",
      "status": "succeeded",
      "amount": 2500,
      "currency": "gbp",
      "metadata": {
        "order_id": "42"
      }
    }
  }
}

BoxCart reads the raw request body via $request->get_body() and retrieves the signature header via $request->get_header('stripe-signature'). The JSON payload is decoded only after signature verification passes.

Response Codes

The webhook endpoint returns the following HTTP status codes.

Stripe considers any 2xx response as successful delivery. If your endpoint returns a non-2xx response, Stripe will retry the delivery with exponential backoff for up to 3 days.

Testing Webhooks

There are two primary ways to test webhook delivery during development.

Using the Stripe CLI

The Stripe CLI lets you forward webhook events to your local development environment without needing a publicly accessible URL.

stripe listen --forward-to yoursite.com/wp-json/boxcart/v1/webhook/stripe

The CLI will output a webhook signing secret (starting with whsec_). Copy this temporary secret and paste it into your BoxCart webhook secret setting for local testing.

You can then trigger test events from another terminal:

stripe trigger payment_intent.succeeded

Using the Stripe Dashboard

If your site is publicly accessible (e.g. a staging server), you can send test events directly from the Stripe Dashboard:

1. Go to Developers → Webhooks in the Stripe Dashboard.
2. Click on your webhook endpoint.
3. Click Send test webhook.
4. Select an event type (e.g. payment_intent.succeeded) and click Send test webhook.

Check the endpoint's Recent deliveries section to see the request and response details, including status codes and any error messages.