Webhook

Learn how to end subscription events to your server with webhook

Adapty's webhook enables you to receive real-time notifications about subscription events. You can utilize this information on your own server to perform specific actions or analyze data. These subscription events are then forwarded to your designated web server.

Setup the Endpoint URL

To setup the integration with Webhook go to Integrations > Webhook in your Adapty dashboard, turn on a toggle from off to on, and fill out fields.

Webhook Integration

Webhook integration

  • Production endpoint URL is used by Adapty to send HTTP POST requests to this URL when events occur. We’ll send an isMount event to your endpoint upon saving, and it must respond with a 200 HTTP code.
  • Authorization header value for production endpoint is by your server to verify the validity of the requests made from Adapty. This field is optional but is recommended to be set up for better security.

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

  • Sandbox endpoint URL: Adapty will use this URL to send HTTP POST requests when events occur in the staging environment. Similar to production, your endpoint must respond with a 200 HTTP code upon receiving the isMount event.
  • Authorization header value for sandbox endpoint: This field is optional but advisable for enhanced security in the staging environment. Your server can validate requests from Adapty using this value during testing in the sandbox environment.

Request format

📘

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

Whenever an event occurs, Adapty triggers a POST request to the endpoint URL.

When you activate a Webhook, Adapty sends a POST verification event in the following format:

{
    adapty_check: {{check_string}}
}

Your server must respond with 200 or 201 code and return the event containing:

{
    adapty_check_response: {{check_string}}
}

with the same check_string

After that Adapty sends POST events about your users.

Event structure

Refer to the Events section to understand which events Adapty sends.

Each event is wrapped into the following structure

{
  "profile_id": "772204ce-ebf6-4ed9-82b0-d8688ab62b01",
  "customer_user_id": "123",
  "idfv": "00000000-0000-0000-0000-000000000000",
  "idfa": "00000000-0000-0000-0000-000000000000",
  "advertising_id": "00000000-0000-0000-0000-000000000000",
  "profile_install_datetime": "2020-02-18T18:40:22.000000+0000",
  "user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 15_4_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Mobile/15E148",
  "email": "[email protected]",
  "event_type": "non_subscription_purchase",
  "event_datetime": "2023-02-18T18:40:22.000000+0000",
  "event_properties": <event-specific properties>,
  "event_api_version": 1,
  "attributions": {"attribution_source1": <attribution_data>, "attribution_source2": <attribution_data>, ...},
  "user_attributes": {"attribute_name1": "attribute_value1", "attribute_name2": "attribute_value2", ...}
  "integration_ids": {"firebase_app_instance_id": "val1", "branch_id": "val2", "one_signal_player_id": "val3", ... }
}

Where

PropertyTypeDescription
profile_idstrAdapty user ID.
customer_user_idstrDeveloper user ID. For example, it can be your user UUID, email, or any other ID. Null if you didn't set it.
idfvstrIDFV value.
idfastrIDFA value.
advertising_idstrAdvertising ID value.
profile_install_datetimeISO 8601 dateInstallation date.
user_agentstrUser agent used by the browser on the device
emailstrE-mail of the profile.
event_typestrEvent name in lower case.
event_api_versionintAdapty API version. The current value is 1.
event_propertiesjsonJSON of event properties.
attributionsjsonJSON of attribution data.
user_attributesjsonJSON of custom user attributes.
integration_idsjsonJSON of users integration identifiers. If a user doesn't have any identifier or integrations are disabled, then a null is sent.

Webhook integration enables to control of sending attribution and user attributes. You can find Send Attribution and Send User Attributes in the Webhook integration page of your Adapty Dashboard. Enabling the Send Attribution option will send information about the source of app installs from data providers. Enabling the Send User Attributes option will send custom user attributes set up from the Adapty SDK, such as user preferences and app usage data.

Handling webhook events

In case the response status code from your server falls outside the 200-404 range, Adapty will make up to 9 attempts to resend the event to the webhook within the following 24 hours with exponential backoff. We encourage implementing your webhook in such a way that only basic validation of the event body received from Adapty is performed before responding. If the event cannot be processed by your server and you do not want Adapty to resend the events, we recommend using a status code within the 200-404 range inclusive. We also recommend implementing all time-consuming logic in asynchronous code, and to send a response to Adapty as quickly as possible. Should Adapty not receive a response within 10 seconds of sending the event, the attempt to send will be considered a failure, and subsequent retries will be initiated.

Event names mapping

You can change the mapping from default Adapty event names to your own:

Changing event name

The name can be any string except a blank.

Attribution data

Field nameField typeDescription
network_user_idstrID assigned to the user by attribution source.
statusstrCan be organic, non_organic or unknown
created_atISO 8601 dateDate and time of attribution record creation.
channelstrMarketing channel name.
campaignstrMarketing campaign name.
ad_groupstrAttribution ad group.
ad_setstrAttribution ad set.
creativestrAttribution creative keyword.