Set up webhook integration

Learn how to set up webhook integration to receive subscription events on your server.

Adapty webhook integration consists of the following steps:

  1. You set up your endpoint to have the Content-Type header as application/json.
  2. You configure the integration in the Adapty Dashboard. Within this step, you can optionally map Adapty events with your event names.
  3. Adapty sends a verification request to your server.
  4. Your server sends a verification response to Adapty
  5. Test your webhook integration.

Configure webhook integration in the Adapty Dashboard

Within Adapty, you can configure separate flows for production events and test events received from the Apple or Stripe sandbox environment or Google test account.

For production events, use the Production endpoint URL field specifying the URL to which the callbacks will be sent. Additionally, configure the Authorization header value for production endpoint field - the header for your server to authenticate Adapty events. Note that we'll use the value specified in the Authorization header value for production endpoint field as the Authorization header exactly as provided, without any changes or additions.

For test events, employ the Sandbox endpoint URL and Authorization header value for sandbox endpoint fields accordingly.

To set up the webhook integration:

  1. Open Integrations -> Webhook in your Adapty Dashboard.
Webhook Integration
  1. Turn on the toggle to initiate the integration.

  2. Fill out the integration fields:

    FieldDescription
    Production endpoint URLURL that is used by Adapty to send HTTP POST requests to this URL when events occur.
    Authorization header value for production endpointThe header that your server will use to authenticate requests from Adapty in production. Note that we'll use the value specified in this field as the Authorization header exactly as provided, without any changes or additions.

    Although not mandatory, it's strongly recommended for enhanced security.

    Additionally, for your testing needs in the staging environment, two other fields are available:

    Testing fieldDescription
    Sandbox endpoint URLAdapty will use this URL to send HTTP POST requests when events occur in the staging environment.
    Authorization header value for sandbox endpointThe header that your server will use to authenticate requests from Adapty during testing in the sandbox environment. Note that we'll use the value specified in this field as the Authorization header exactly as provided, without any changes or additions.

    Although not mandatory, it's strongly recommended for enhanced security.
  3. Choose the events you want to receive and map their names.

  4. Additional fields and options are not obligatory; use them as needed.

  5. Remember to click the Save button to confirm the changes.

Please note that the moment you click the Save button, Adapty will send a verification request and will wait for your server verification response.

Choose events to send and map event names

Choose the events you want to receive in your server by enabling the toggle next to it. If your event names differ from those used in Adapty and you need to keep your names as is, you can set up the mapping by replacing the default Adapty event names with your own in the Events names section of the Integrations -> Webhooks page.

Changing event name

The event name can be any string. You cannot leave the fields empty for enabled events. If you accidentally removed Adapty event name, you can always copy the name from the Events to send to 3d-party integrations topic.

Adapty's verification request

After you enable webhook integration in the Adapty Dashboard, Adapty will automatically send a isMount POST verification request to your endpoint.

{
    adapty_check: {{check_string}}
}

📘

Be sure your endpoint has Content-Type: application/json header.

Your server's verification response

Your server must reply with a 200 or 201 HTTP status code and send the response outlined below with the identical check_string.

{
    adapty_check_response: {{check_string}}
}

Once Adapty receives the verification response in the correct format, your Adapty webhook integration is fully configured.

From then on, Adapty will send the selected events to your specified URL as they happen. Ensure your server promptly confirms each Adapty event with a response status code in the 200-404 range.

Handle webhook events

Webhooks are typically delivered within 5 to 60 seconds of the event occurring. Cancellation events, however, may take up to 2 hours to be delivered after a user cancels their subscription.

If your server's response status code is outside the 200-404 range, Adapty will retry sending the event up to 9 times over 24 hours with exponential backoff. We suggest you set up your webhook to do only basic validation of the event body from Adapty before responding. If your server can't process the event and you don't want Adapty to retry, use a status code within the 200-404 range. Also, handle any time-consuming tasks asynchronously and respond to Adapty quickly. If Adapty doesn't receive a response within 10 seconds, it will consider the attempt a failure and will retry