> For the complete documentation index, see [llms.txt](https://docs.sparkloop.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sparkloop.app/webhooks.md). # Webhooks ## Webhooks Webhooks are used to send events from SparkLoop to your server. We send a `POST HTTP` request with a JSON payload when specific events occur. ### Create a webhook To create a webhook: * go to your [*Account Settings > Integrations*](https://dash.sparkloop.app/settings/integrations) * enter the URL of your webhook and choose which events you want to receive
### Update/delete a webhook To update or delete a webhook hover over the three dots to the right of the webhook to open the settings menu and click on the link to update or delete.
### Test a webhook To test a webhook hover over the three dots to the right of the webhook to open the settings menu and click on "Send test webhook" ![](https://307340109-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LvjCB8kc4yvMRscfT0m%2Fuploads%2FhoH0v7BKT7IWilrJaSTm%2Fimage.png?alt=media\&token=dfbe0caf-7a61-48ff-ad6c-1a338512de7d) ### Authentication token SparkLoop authenticates all webhooks with a token in the `SparkLoop-Token` request header. This allows you to verify that the events were sent by SparkLoop, not by a third party. While this is entirely optional, it adds an extra layer of security: simply check the token in the `SparkLoop-Token` header is the same as your authentication token. If not, ignore the webhook! You can find your authentication token in [your Webhooks page](https://dash.sparkloop.app/settings/integrations). ### Events #### **new\_referral** Is sent when a new referral made by a subscriber in a referral program is tracked ```json { "type": "new_referral", "campaign_id": "MF6319db9890", "subscriber": { "id": "sub_hjdgc74u", "first_name": "John", "name": "John Doe", "email": "john.doe@email.com", "referral_code": "ada90f39", "referral_link": "https://mywebsite.com?rh_ref=ada90f39", "referred": true, "tot_referrals": 0, "next_reward": 2, "created_at": 1564400550 }, "referrer": { "id": "sub_93ehus8h", "first_name": "John", "name": "John Smith", "email": "john.smith@email.com", "referral_code": "f9464199", "referral_link": "https://mywebsite.com?rh_ref=f9464199", "referred": false, "tot_referrals": 4, "next_reward": 1, "created_at": 1564403873 } } ``` #### **new\_partner\_pending\_referral** Is sent when a referral made by a partner is starts the screening period ```json { "type": "new_partner_pending_referral", "campaign": { "id": "partner_campaign_de9c1c7c7bbc", "referral_code": "1b5b5c4094", "type": "partner_program", "upscribe": true, "partner_program_id": "partner_program_5b925f623c28" "publication_id": "pub_a6db3f666c55", "created_at": 1658780774 }, "subscriber": { "id": "sub_042448acb02a", "first_name": null, "name": null, "email": "test12345@test.com", "referral_code": "6363a0b5", "referred": true, "tot_referrals": 0, "referral_status": "pending", "last_reward": null, "partner_id": "partner_0a8a45c403f8", "created_at": 1659536359 }, "partner": { "id": "partner_0a8a45c403f8", "name": "Jason Resnickss", "logo": "http://dash.sparkloop.app/rails/active_storage/representations/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBPQT09IiwiZXhwIjpudWxsLCJwdXIiOiJibG9iX2lkIn19--36ac8d234a450db1db32c62fe9e399b29a9e42f0/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaDdCam9VY21WemFYcGxYM1J2WDJ4cGJXbDBXd2RwQVpacEFaWT0iLCJleHAiOm51bGwsInB1ciI6InZhcmlhdGlvbiJ9fQ==--b97dd663f95aeeb4752185ef091f0728b0f28f4a/active_campaign.png" } } ``` #### **new\_partner\_referral** Is sent when a referral made by a partner is confirmed ```json { "type": "new_partner_referral", "campaign": { "id": "partner_campaign_de9c1c7c7bbc", "referral_code": "1b5b5c4094", "type": "partner_program", "upscribe": true, "partner_program_id": "partner_program_5b925f623c28" "publication_id": "pub_a6db3f666c55", "created_at": 1658780774 }, "subscriber": { "id": "sub_042448acb02a", "first_name": null, "name": null, "email": "test12345@test.com", "referral_code": "6363a0b5", "referred": true, "tot_referrals": 0, "referral_status": "verified", "last_reward": null, "partner_id": "partner_0a8a45c403f8", "created_at": 1659536359 }, "partner": { "id": "partner_0a8a45c403f8", "name": "Jason Resnickss", "logo": "http://dash.sparkloop.app/rails/active_storage/representations/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBPQT09IiwiZXhwIjpudWxsLCJwdXIiOiJibG9iX2lkIn19--36ac8d234a450db1db32c62fe9e399b29a9e42f0/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaDdCam9VY21WemFYcGxYM1J2WDJ4cGJXbDBXd2RwQVpacEFaWT0iLCJleHAiOm51bGwsInB1ciI6InZhcmlhdGlvbiJ9fQ==--b97dd663f95aeeb4752185ef091f0728b0f28f4a/active_campaign.png" } } ``` #### **new\_offer\_lead** Is sent when a new lead is confirmed ```json { "type": "new_offer_lead", "offer_id": "offer_de9c1c7c7bbc", "lead": { "id": "offer_conversion_an324nf332f", "email": "test12345@test.com", "source": "sparkloop-upscribe", "partner_id": "partner_0a8a45c403f8", "referral_status": "confirmed", "offer_recommendation_id": "offer_recommendation_dsfhgfb476f, "created_at": 1659536359, "referred_at": 1659536359 }, "partner": { "id": "partner_0a8a45c403f8", "name": "Jason Resnickss", "logo": "http://dash.sparkloop.app/rails/active_storage/representations/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBPQT09IiwiZXhwIjpudWxsLCJwdXIiOiJibG9iX2lkIn19--36ac8d234a450db1db32c62fe9e399b29a9e42f0/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaDdCam9VY21WemFYcGxYM1J2WDJ4cGJXbDBXd2RwQVpacEFaWT0iLCJleHAiOm51bGwsInB1ciI6InZhcmlhdGlvbiJ9fQ==--b97dd663f95aeeb4752185ef091f0728b0f28f4a/active_campaign.png" } } ``` #### **new\_opportunity** Is sent when an enriched subscriber's sponsorship opportunity score first reaches the opportunity threshold (70 or higher). SparkLoop sends this webhook only once per subscriber — when they first qualify — not on subsequent score updates. You can enable this event from **Account Settings > Integrations** or from the **Opportunities** page in your dashboard. ```json { "type": "new_opportunity", "publication_id": "publication_123", "opportunity": { "score": 85, "detected_at": "2026-07-09T10:00:00Z" }, "person": { "name": "Jane Doe", "email": "jane@example.com", "job_title": "Head of Marketing", "seniority": "Executive", "gender": "Female", "age_range": "35-44", "income_level": "$150k-$200k", "linkedin": "https://linkedin.com/in/janedoe", "twitter": null, "facebook": null, "github": null }, "company": { "name": "Acme Inc", "domain": "acme.com", "industry": "Software", "employees_range": "51-200", "revenue_range": "$10M-$50M" } } ``` The payload includes the same person, company, and score fields as the Opportunities CSV export. Internal scoring reasoning is not included. The `company` object may be omitted if no company data is available. #### new\_survey\_response Is sent when a subscriber completes a Welcome Survey. SparkLoop sends this webhook for every new survey submission. ```json { "type": "new_survey_response", "publication_id": "publication_123", "survey_id": "survey_123", "email": "jane@example.com", "submitted_at": "2026-07-15T10:00:00Z", "responses": [ { "label": "Full name", "value": "Jane Doe" }, { "label": "Company name", "value": "Acme Inc" } ] } ``` #### **reward\_unlocked** Is sent when a subscriber hits a milestone and unlocks a reward ```json { "type": "reward_unlocked", "campaign_id": "MF6319db9890", "referrals": 4, "coupon_code": "9wusha0", "subscriber": { "id": "sub_hjdgc74u", "first_name": "John", "name": "John Doe ", "email": "john.doe@email.com", "referral_code": "f9464199", "referral_link": "https://mywebsite.com?rh_ref=f9464199", "referred": true, "tot_referrals": 4, "next_reward": 2, "created_at": 1564403873 }, "reward": { "id": "reward_cdebf4f013", "name": "2018 Private Report: State of the Ecommerce", "referrals": 4, "recurring": false } } ``` #### **reward\_redeemed** Is sent when a subscriber redeems a reward by submitting their address details. ```json { "type": "reward_redeemed", "campaign_id": "MF6319db9890", "referrals": 4, "coupon_code": "9wusha0", "subscriber": { "id": "sub_hjdgc74u", "first_name": "John", "name": "John Doe ", "email": "john.doe@email.com", "referral_code": "f9464199", "referral_link": "https://mywebsite.com?rh_ref=f9464199", "referred": true, "tot_referrals": 4, "next_reward": 2, "created_at": 1564403873 }, "reward": { "id": "reward_cdebf4f013", "name": "2018 Private Report: State of the Ecommerce", "referrals": 4, "recurring": false }, "reward_variant_name": "T-Shirt XXL", "reward_variant_sku": "t_shirt_xxl", "shipping_details": { "shipping_name": "John Doe", "shipping_phone": "+01 407-889-2040", "shipping_address_1": "7838 Pearl Drive", "shipping_address_2": null, "shipping_city": "Sun City", "shipping_state_code": "AZ", "shipping_zipcode": "85351", "shipping_country_code": "US" } } ``` #### **sync\_subscriber** Is sent when a referral is created or updated. ```json { "type": "sync_subscriber", "subscriber": { "id": "sub_hjdgc74u", "first_name": "John", "name": "John Doe ", "email": "john.doe@email.com", "referral_code": "f9464199", "referral_link": "https://mywebsite.com?rh_ref=f9464199", "referred": true, "tot_referrals": 4, "referral_status": "rejected", "next_reward": 2, "created_at": 1564403873 } } ``` ### Errors Please send back a blank response with a status code of `200`.\ All not-200 responses will be considered errors.