Outbound Webhooks

What is a webhook?

A webhook is an HTTP callback. KickoffLabs sends a request to your URL when a selected campaign event happens, so your app can receive lead updates in near real time.

What are KickoffLabs webhooks used for?

Use outbound webhooks to send KickoffLabs lead data to your CRM, database, backend service, marketing platform, or automation tool.

How to setup an outbound webhook from KickoffLabs

1. Go to your campaign dashboard and open outbound webhook settings.
2. Select “Add a New Outbound Webhook”.
3. Configure the webhook:
   • Post URL: The URL where KickoffLabs should send data.
   • Events: One or more events that should trigger this URL.
4. Save the webhook.

Most integrations start with the new_signup event. You can subscribe one URL to multiple events.

API setup

You can also create an outbound webhook with the API.

POST https://api.kickofflabs.com/v2/CAMPAIGN_ID/outbound-webhook

Required parameters:

• api_key: Your API key, or send it in an Authorization/Authentication header for JSON requests.
• url: Destination URL. Must start with http.
• event or events: One event or an array of events.

Optional parameters:

• source: Stored with the webhook for source tracking.

Example request:

curl -X POST "https://api.kickofflabs.com/v2/CAMPAIGN_ID/outbound-webhook" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer KEY" \
  -d '{
    "url": "https://example.com/kickofflabs-webhook",
    "events": ["new_signup", "referral"]
  }'

Successful response:

{
  "message": "Webhook Created",
  "referenceId": 123,
  "events": ["new_signup", "referral"]
}

Delete a webhook by URL:

DELETE https://api.kickofflabs.com/v2/CAMPAIGN_ID/outbound-webhook

Required parameters:

• api_key
• url

Supported webhook events

KickoffLabs supports these outbound webhook event names:

• new_signup
• repeat_signup
• score_change
• marked_as_fraudulent
• opted_out
• referral
• tagged
• reward_level
• verified
• phone_number_opt_out
• new_signup_not_excluded
• deleted

For backwards compatibility, API requests that submit fraudulent are converted to marked_as_fraudulent.

Invalid event names return 409 with a message like Invalid event type ....

Data posted with webhooks

KickoffLabs posts the same common lead payload used by the API, plus an __event field containing the event name. See Create Lead API Response for the common lead field reference.

Common data

Common webhook payload data can include:

• Lead identity: id, social_id, email, phone_number, uid
• Campaign identity: campaign_id, list_id
• Name/display: first_name, given_name, family_name, display_name, avatar
• Referral state: rank, counter, lead_count, referrals, referral-count groups, social_url
• Status: verified, verified_email, verified_phone_number, waitlisted, opted_out, sms_opted_out, fraudulent
• Custom data: custom_fields, utm, tags
• URLs: redirect_url, thankyou_url, status_url, unsubscribe_url
• __event: Trigger event name

Event-specific data

Some events add extra fields:

• referral: Adds __referral with the referred lead’s social_id and, when available, email and/or phone_number.
• marked_as_fraudulent: Adds __fraudulent with the lead’s excluded/fraudulent flags.
• score_change: Adds __score_change with score-change event data.
• tagged: Adds __tagged with tag_id, name, and points.
• reward_level: Adds __reward_level with reward_level_id, subject, required_points, and emailed.

Delivery format

By default, KickoffLabs sends webhook payloads as JSON:

• Content-Type: application/json
• Body: JSON string of the lead/event payload
• User-Agent: KickoffLabs

For legacy/backport webhook configurations and URLs containing klaviyo, KickoffLabs sends application/x-www-form-urlencoded data instead.

Technical considerations

• Your endpoint should accept POST requests.
• Treat webhooks as at-least-once delivery and make your handler idempotent.
• Return a 2xx response quickly after receiving the payload.
• Large campaigns can generate significant webhook traffic.
• Store the social_id, campaign_id, list_id, and __event fields to dedupe and debug deliveries.