Sync With Webhooks

Webhooks enable Lemon Squeezy to automatically send data to your application in response to specific store events, ensuring your users remain informed and maintain access to their products.

For instance, when a subscription renewal is processed, information about the payment can be sent directly to an endpoint in your application. You can then utilize and process this data to update your application, ensuring that your users are informed of the renewal and, importantly, maintain access to your product.

Webhook events

There are many different events for which webhooks are sent, such as:

• order_created
• order_refunded
• subscription_created
• subscription_updated
• subscription_cancelled
• subscription_resumed
• subscription_expired
• subscription_paused
• subscription_unpaused
• subscription_payment_failed
• subscription_payment_success
• subscription_payment_recovered
• license_key_created
• license_key_updated

Example webhook data

Webhook events are sent as JSON via POST requests to your endpoint.

The data that is available in each webhook request is either a Subscription, Subscription invoice, Order or License key object. Each of our webhooks follows the same structure as below.

An example subscription_created event’s request looks like this:

{
  "meta": {
    "event_name": "subscription_created"
  },
  "type": "subscriptions",
  "id": "1",
  "attributes": {
    "store_id": 1,
    "customer_id": 1,
    "order_id": 1,
    "order_item_id": 1,
    "product_id": 1,
    "variant_id": 1,
    "product_name": "Lemonade",
    "variant_name": "Citrus Blast",
    "user_name": "John Doe",
    "user_email": "[email protected]",
    "status": "active",
    "status_formatted": "Active",
    "card_brand": "visa",
    "card_last_four": "42424",
    "pause": null,
    "cancelled": false,
    "trial_ends_at": null,
    "billing_anchor": 12,
    "first_subscription_item": {
      "id": 1,
      "subscription_id": 1,
      "price_id": 1,
      "quantity": 5,
      "created_at": "2021-08-11T13:47:28.000000Z",
      "updated_at": "2021-08-11T13:47:28.000000Z"
    },
    "urls": {
      "update_payment_method": "https://my-store.lemonsqueezy.com/subscription/1/payment-details?expires=1666869343&signature=9985e3bf9007840aeb3951412be475abc17439c449c1af3e56e08e45e1345413",
      "customer_portal": "https://my-store.lemonsqueezy.com/billing?expires=1666869343&signature=82ae290ceac8edd4190c82825dd73a8743346d894a8ddbc4898b97eb96d105a5",
      "customer_portal_update_subscription": "https://my-store.lemonsqueezy.com/billing/1/update?expires=1666869343&signature=e4fabc7ee703664d644bba9e79a9cd3dd00622308b335f3c166787f0b18999f2"
    },
    "renews_at": "2022-11-12T00:00:00.000000Z",
    "ends_at": null,
    "created_at": "2021-08-11T13:47:27.000000Z",
    "updated_at": "2021-08-11T13:54:19.000000Z",
    "test_mode": false
  }
}

You can see in the example above that the data object is a Subscription object.

If you added custom data to the checkout, it will be available in meta.custom_data:

{
  "meta": {
    "event_name": "subscription_created",
    "custom_data": {
      "user_id": 123
    }
  },
  "data": {
    "type": "subscriptions",
    ...
  }
}

When you receive webhook events at your endpoint, it’s important to update your application’s local data, such as the order ID, renewal date, status, or payment method URL.

In addition to the primary data, each webhook includes relationships to related objects within Lemon Squeezy. You can use the provided URLs to perform sequential GET requests to access these related objects. For example, you can retrieve a product variant object by using the URL found in relationships.variant.links.related.

Creating webhooks

Setting up webhooks is quick and easy. You can create and manage webhooks in two ways:

1. From your Lemon Squeezy dashboard
2. Using the Lemon Squeezy Webhooks API

POST https://api.lemonsqueezy.com/v1/webhooks

{
  "data": {
    "type": "webhooks",
    "attributes": {
      "url": "https://example.com/webhooks/",
      "events": [
        "order_created",
        "subscription_created",
        "subscription_updated",
        "subscription_expired"
      ],
      "secret": "SIGNING_SECRET"
    },
    "relationships": {
      "store": {
        "data": {
          "type": "stores",
          "id": "1"
        }
      }
    }
  }
}

Adding an endpoint in your app

You will need an endpoint in your app that serves as the receiver for all webhook requests. This should accept POST requests and be able to process and/or save each webhook as it is sent.

To tell Lemon Squeezy that a webhook request was recieved OK, return a HTTP 200 response. Any other response code will tell Lemon Squeezy that the webhook failed and the event will be sent again up to three more times. If your app has not returned a HTTP 200 response by the fourth attempt, the event will not be tried again automatically, though you can re-send recent webhooks from your webhooks settings.

We recommend storing webhook events locally, either in your database or a cache, even if only temporarily. This approach allows you to quickly return an HTTP 200 response and process the data outside of the webhook request. Additionally, if your app encounters an issue while processing a webhook, you will have the necessary data on hand to troubleshoot and fix the problem without waiting for the event to be resent.

Signing and validating webhook requests

To check that data sent to your specified webhook endpoint is actually from Lemon Squeezy, you should verify the signature that is sent along with the event data.

The signature is sent in the X-Signature header and is a hash made up of the signing secret you specified when creating the webhook in your Lemon Squeezy account plus the request body.

To verify the webhook is from Lemon Squeezy you should attempt to create a matching hash and check that it matches the signature in the header.

Simulate subscription webhooks in “Test mode”

We know building an API integration can be difficult, especially when you need to test subscription webhook events that happen in the future and can’t be easily tested via the checkout.

This is why we built a webhook simulation feature. When in “Test mode”, you can manually trigger certain subscription events from your Lemon Squeezy account.

Once you have some subscriptions in your test mode account (you can create these by purchasing products through the test mode checkout) you will see a “Simulate event” option in each subscription’s side panel. Simply select the event you want to trigger and a matching event will be sent to your endpoint.

Subscription renewal events

To test subscription renewal events (subscription_payment_*), you need at least one renewal to have occurred on a subscription. We generate simulation webhooks based on this renewal data. For quicker testing:

1. Create test subscription products with daily billing intervals
2. Purchase a subscription to one of these products
3. Wait for the first renewal (which will occur the next day)
4. You’ll then be able to simulate subscription_payment_* events for this subscription

And that’s it! You’re now equipped to set up, receive, and process webhooks from Lemon Squeezy. With this real-time data flow, your app will always be in sync with your store events. Happy coding!