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

• 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"

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.

Events

new_referral

Is sent when a new referral made by a subscriber in a referral program is tracked

{
  "type": "new_referral",
  "campaign_id": "MF6319db9890",
  "subscriber": {
    "id": "sub_hjdgc74u",
    "first_name": "John",
    "name": "John Doe",
    "email": "[e-mail]",
    "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": "[e-mail]",
    "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

{
  "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": "[e-mail]",
    "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

{
  "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": "[e-mail]",
    "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

{
  "type": "new_offer_lead",
  "offer_id": "offer_de9c1c7c7bbc",
  "lead": {
    "id": "offer_conversion_an324nf332f",
    "email": "[e-mail]",
    "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.

{
  "type": "new_opportunity",
  "publication_id": "publication_123",
  "opportunity": {
    "score": 85,
    "detected_at": "2026-07-09T10:00:00Z"
  },
  "person": {
    "name": "Jane Doe",
    "email": "[e-mail]",
    "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.

{
  "type": "new_survey_response",
  "publication_id": "publication_123",
  "survey_id": "survey_123",
  "email": "[e-mail]",
  "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

{
  "type": "reward_unlocked",
  "campaign_id": "MF6319db9890",
  "referrals": 4,
  "coupon_code": "9wusha0",
  "subscriber": {
    "id": "sub_hjdgc74u",
    "first_name": "John",
    "name": "John Doe ",
    "email": "[e-mail]",
    "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.

{
  "type": "reward_redeemed",
  "campaign_id": "MF6319db9890",
  "referrals": 4,
  "coupon_code": "9wusha0",
  "subscriber": {
    "id": "sub_hjdgc74u",
    "first_name": "John",
    "name": "John Doe ",
    "email": "[e-mail]",
    "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.

{
  "type": "sync_subscriber",
  "subscriber": {
    "id": "sub_hjdgc74u",
    "first_name": "John",
    "name": "John Doe ",
    "email": "[e-mail]",
    "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.