Campaign Creator Webhooks

Receive notifications when creators are added, removed, have their affiliate code updated, or generate sales on campaigns

Prerequisite You need administrative access to your Growi dashboard to configure webhook URLs.

Overview

When a brand has one or more Webhook URLs configured, Growi will send an HTTP POST request with a JSON body whenever a campaign’s creator affiliation changes state, a creator’s affiliate code is updated, or a creator generates an attributed sale.

Configuration

In the Organization settings, configure:

• Webhook URLs: One or more HTTPS destinations. Every active destination receives every event.

Event Types

The webhook payload includes an event field to differentiate between actions:

Event	Description
campaign_affiliate.activated	Creator was added/activated on the campaign
campaign_affiliate.removed	Creator was removed from the campaign
campaign_affiliate.left	Creator left the campaign
campaign_affiliate.code_updated	Creator’s affiliate code (tag) was changed
affiliate_sale.created	A sale was attributed to one of your creators

If the system encounters an unknown status, it will fall back to campaign_affiliate.<status>.

Delivery Details

Setting	Value
Method	POST
Content-Type	application/json
Connect Timeout	10 seconds
Read Timeout	30 seconds
Success Criteria	Any 2xx response
Retries	Up to 3 retries on failure

Non-2xx responses are treated as failures and will be retried. Delivery is at-least-once: use the payload’s idempotency_key to deduplicate.

Payload Format

The request body is a single JSON object with the following fields:

event · string · required

Event name that indicates what happened.

occurred_at · string · required

ISO-8601 timestamp of the underlying record update.

campaign_affiliate_id · integer · required

Internal ID of the campaign-creator association record.

campaign_id · integer · required

Campaign ID.

organization_id · integer · required

Organization ID.

user_id · integer · required

Creator’s user ID.

status · string · required

The raw status value on the record (e.g., active, removed, left).

campaign_name · string

Campaign name, when available.

organization_slug · string

Brand slug, when available.

user_email · string

Creator email, when available.

user_name · string

Creator name, when available.

tag · string

Default affiliate tag for the creator on this campaign, when available. For code_updated, this is the new code.

previous_tag · string

Present on campaign_affiliate.code_updated only. The affiliate code before the change.

idempotency_key · string

Stable key for deduplicating redelivered events (delivery is at-least-once).

attribution · object

Present when the creator was submitted through the campaign applications API. Echoes the marketing attribution you sent with the applicant — fbp, fbc, fbclid, event_id, event_source_url, UTM parameters, your external_id, and TikTok enrichment — so you can match the creator in your ad platform (for example, forwarding to Meta Conversions API).

Optional fields are omitted when values are not present. For status events, occurred_at uses the campaign affiliation record’s updated_at timestamp. For code_updated, it is the time the code change was committed.

Sale Events

affiliate_sale.created fires when a sale is attributed to one of your creators (Shopify, website/API conversions, and app sales). On top of the shared fields above (campaign_name, organization_slug, user_email, user_name, tag, attribution), the payload carries:

affiliate_sale_id · integer · required

Growi’s id for the sale.

order_id · string · required

The external order id (e.g. the Shopify order).

total_cents · integer · required

Order total in cents.

subtotal_cents · integer

Order subtotal in cents.

commission_cents · integer

The creator’s commission in cents.

currency · string · required

ISO currency code (lowercase, e.g. usd).

platform · string · required

shopify, website, ios, or android.

sale_type · string

one_time or subscription.

sale_occurrence · string

initial for the customer’s first attributed sale, recurring for later purchases.

status · string

Payout status of the sale (e.g. unpaid).

Example Payloads

Creator Added to Campaign

{
  "event": "campaign_affiliate.activated",
  "occurred_at": "2026-02-27T18:33:12-05:00",
  "campaign_affiliate_id": 123,
  "campaign_id": 456,
  "organization_id": 789,
  "user_id": 42,
  "status": "active",
  "campaign_name": "Spring Promo",
  "organization_slug": "acme",
  "user_email": "[e-mail]",
  "user_name": "Creator Name",
  "tag": "creator-default-tag",
  "idempotency_key": "campaign_affiliate.activated:123:2026-02-27T18:33:12-05:00",
  "attribution": {
    "fbp": "fb.1.1785503550741.5188770206",
    "fbc": "fb.1.1785503550741.PAcGRvZgJmZGlk",
    "event_id": "012e8a42-6b26-43cf-9a66-0242c6bc0fd1",
    "event_source_url": "https://shop.example.com/tiktok-partner",
    "utm_source": "facebook",
    "external_id": 11177
  }
}

attribution appears only for creators submitted through the campaign applications API. Approval events are delivered a couple of minutes after the approval, once the creator’s affiliate code has been generated.

Sale Attributed to a Creator

{
  "event": "affiliate_sale.created",
  "idempotency_key": "affiliate_sale.created:31337",
  "occurred_at": "2026-08-20T12:00:00Z",
  "affiliate_sale_id": 31337,
  "order_id": "5723098317101",
  "campaign_affiliate_id": 123,
  "campaign_id": 456,
  "organization_id": 789,
  "user_id": 42,
  "total_cents": 5900,
  "subtotal_cents": 5400,
  "commission_cents": 590,
  "currency": "usd",
  "platform": "shopify",
  "sale_type": "one_time",
  "sale_occurrence": "initial",
  "status": "unpaid",
  "campaign_name": "Spring Promo",
  "organization_slug": "acme",
  "user_email": "[e-mail]",
  "user_name": "Creator Name",
  "tag": "creator-default-tag",
  "attribution": {
    "fbp": "fb.1.1785503550741.5188770206",
    "event_id": "012e8a42-6b26-43cf-9a66-0242c6bc0fd1",
    "utm_source": "facebook",
    "external_id": 11177
  }
}

Creator Removed from Campaign

{
  "event": "campaign_affiliate.removed",
  "occurred_at": "2026-02-27T18:35:02-05:00",
  "campaign_affiliate_id": 123,
  "campaign_id": 456,
  "organization_id": 789,
  "user_id": 42,
  "status": "removed"
}

Creator Affiliate Code Updated

{
  "event": "campaign_affiliate.code_updated",
  "occurred_at": "2026-07-14T16:10:00-04:00",
  "campaign_affiliate_id": 123,
  "campaign_id": 456,
  "organization_id": 789,
  "user_id": 42,
  "status": "active",
  "campaign_name": "Spring Promo",
  "organization_slug": "acme",
  "user_email": "[e-mail]",
  "user_name": "Creator Name",
  "previous_tag": "old-code",
  "tag": "new-code"
}

Troubleshooting

Webhook Not Being Received

Ensure your webhook URL is correctly configured in Organization settings and is publicly accessible over HTTPS.

Receiving Duplicate Events

Implement idempotency in your webhook handler using the idempotency_key field to deduplicate events (for older payloads without it, combine campaign_affiliate_id, event, and occurred_at).

Webhook Failing with Timeout

Your endpoint must respond within 10 seconds. Consider processing webhooks asynchronously and returning a 200 response immediately.

Got removed when changing a code

Changing a creator’s affiliate code does not remove them from the campaign. Status webhooks (activated / removed / left) only fire on status changes. Code changes emit campaign_affiliate.code_updated instead. If you received a removed event around a code change, check whether the creator was also removed (or a delayed status webhook from an earlier action was delivered).