A webhook is a convenient and fast way to get notifications about events. For example, if a new trial is started, a subscription is renewed, or a billing issue happens. The webhook mechanism works through a callback function. You set up a URL (called Endpoint URL) to which an HTTP request is sent when an event occurs.

Unlike API requests, which require repeatedly requesting information from the server, a webhook is configured only once. When the target event occurs in your app, it immediately sends data via the HTTP protocol.

With webhooks integrated, you can:

• Keep track of subscriptions and purchases in your backend system.
• Automate processes and workflows based on subscription lifecycles.
• Engage with subscribers by reminding them of app benefits, addressing unsubscribe decisions, and handling billing issues.
• Conduct a detailed analysis of the user behavior.

Integration characteristics

Webhook event structure

Adapty will send you those events you've chosen in the Events names section of the Integrations -> Webhooks page.

Each event except for the access_level_update is wrapped into the structure below. Empty fields are not sent. For example, the line "ad_group": null will not be included into the package.

{
  "profile_id": "772204ce-ebf6-4ed9-82b0-d8688ab62b01",
  "customer_user_id": "john.doe",
  "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

🚧

Note that this structure may grow over time — with new data being introduced by us or by the 3rd parties we work with. Make sure that your code that processes it is robust enough and relies on the specific fields, but not on the structure as a whole.

Webhook integration enables the control of sending attribution and user attributes.

• Enable the Send Attribution option in the Integrations -> Webhooks page to send the information about the source of app installs from data providers.
• Enable the Send User Attributes option to send custom user attributes set up from the Adapty SDK, such as user preferences and app usage data.

Event Access level updated

Adapty has a special event access_level_updated. It is sent only to webhook integration every time the access level is updated/set for a specific customer. Use this event to update a customer's subscription in your database/system. No matter what was the source of access level changes, you will always receive a dedicated event for that, therefore it's more precise and has more details than subscription_renewed, trial_started, entered_grace_period, etc.

Adapty doesn't send access_level_updated upon subscription expiration - please, refer to expires_at value to end the subscriptions on your side.

Please note that some properties can only be set using the grant Server-Side API method. You can find more information about this method in the Adapty Server-Side API documentation.

For detailed descriptions of the mentioned properties, you can refer to the API objects documentation.

Attribution data

If you've chosen to send attribution data, the following data will be sent with the event: