API Webhooks for Advocate Programs

Webhooks let you register a URL that we will POST to any time an event happens in your program. When the event occurs, for example when a vanity coupon code is created for a new participant, an event object is created. This object contains all the relevant information, including the type of event and the data associated with that event. Advocate then sends an HTTP POST request with the event object to any URLs in your account's webhook settings. You can find a full list of all event types below.

Multiple Subscriptions

Multiple endpoints may be subscribed, in which case each endpoint will be notified using the behavior described above. Duplicate endpoint URLs will simply result in one subscription being created for that URL.

Delivery Order

Delivery order of events is not guaranteed and delivery timing is not guaranteed. Avoid building logic that relies on a specific delivery ordering of webhook notifications.

Retry Policy

Rest hooks are delivered immediately after an event is triggered. If the endpoint does not successfully respond to a delivery attempt (i.e., respond with a status code other than 200), the delivery will be considered as failed. Failed deliveries will be reattempted every hour after the previous failed attempt until either a successful delivery is made or until 72 attempts have been made (approximately 3 days at the rate of 1 retry per hour).

Webhook Management API Endpoints

To use webhooks, you need a subscription first. These API endpoints can be used to create and manage the subscriptions that will receive webhook events.

Webhook events

Event type	Description
user.created	Sent whenever a new User is created.
user.reward.balance.changed	Sent whenever a rewards balance is updated from new rewards, redemption, cancellation, or expiry. Only works with all `unit` types for `CREDIT` rewards, including `POINTS`, `CASH/USD`, and others.
coupon.created	Sent whenever a new referral code is created.
reward.created	Sent whenever a new reward is created.
referral.started	Sent whenever a new referral connection is successfully established.
referral.converted	Sent whenever a referral is converted.
export.created	Sent whenever a data export for a tenant is queued for creation.
export.completed	Sent whenever an export that was being generated for a tenant has completed and is ready to be downloaded.
test	Sent to test a subscription.

Payloads

All webhook data conforms to the same data format.

id	String - A unique identifier for this event
type	String - The type of event
tenantAlias	String - The tenant used to create this data
live	Boolean - True for Live tenants and false for Test tenants
created	Number - The timestamp when this event was created
data	An arbitrary JSON object containing data related to this event

Webhook event details

After a webhook subscription is created, it will immediately start receiving webhook payloads. Each payload has a noted type field which can be used to differentiate between events. New event types may be added to the API, so avoid building logic that assumes it knows all event types.

`user.created`

Sent whenever a new User is created. Only fires when a new user is created, not for updates or deletes.

⚠️
Note:
Users can be created via the REST API or UTT, the referral widget, or a batch upload process.

{  
  "id": "577303ece4b066c5cb171835",  
  "type": "user.created",  
  "tenantAlias": "aohgcctyskc0p",  
  "live": true,  
  "created": 1467155436449,  
  "data": {  
    "id": "sat09jsaet09setset",  
    "accountId": "90w4etjsa4et",  
    "email": "[[email protected]](mailto:[email protected])",  
    "firstName": "Mike",  
    "lastName": "Keenerson",  
    "referralCodes": {  
      "referral-program": "MIKEKEENERSON",  
      "partner-program": "FREE"  
    },  
    "imageUrl": "",  
    "firstSeenIP": "10.230.163.157",  
    "lastSeenIP": null,  
    "dateCreated": 1467155436418,  
    "locale": "fr_CA",  
    "countryCode": "CA",  
    "programShareLinks": {  
      "partner-program": {  
        "cleanShareLink": "<http://example.com/free">,  
        "MOBILE": {  
          "DIRECT": "<http://example.com/free?me">  
        },  
        "EMAIL": {  
          "DIRECT": "<http://example.com/free?mP">  
        },  
        "UNKNOWN": {  
          "DIRECT": "<http://example.com/free?mv">  
        }  
      }  
    },  
    "customFields": {  
      "birthday": "--02-29"  
    },  
    "segments": ["segment1"],  
    "referredByCodes": ["CODE1"]  
  }  
}

user.reward.balance.changed

Sent whenever a rewards balance is updated. Only works with all unit types for CREDIT rewards, including POINTS, CASH/USD, CENTS, and others.

Examples of what might change a balance:

A credit reward is given to a user
A pending credit reward is made available to a user
A user's reward expires
A user's reward is cancelled
A user's reward is fully redeemed
A user's reward is partially redeemed

Other rules to consider:

The user.reward.balance.changed webhook only applies to CREDIT rewards. PCT_DISCOUNT, FUELTANK and INTEGRATION rewards won't trigger this webhook.
The creation of a pending reward will not trigger a balance update because it doesn't affect the balance.
This webhook is per unit balance changed (we don't combine balances in a single webhook).
This webhook contains an available balance value calculated after (not exactly at) the time of the trigger.
No balance update webhook is sent when a user is deleted and any external user balance will remain at its last known value.

Eventual consistency

Webhooks can also arrive at your application out-of-order. This can be due to issues such as network delays or webhook failures. However, you can order the events by examining the resourceVersion attribute of the resource sent by the webhook to ensure Eventual Consistency.

Since resourceVersion is incremented for changes made to the balance, you can only accept the latest data, and ignore old data.

{  
  "id": "577303ece4b066c5cb171835",  
  "type": "user.reward.balance.changed",  
  "tenantAlias": "aohgcctyskc0p",  
  "live": true,  
  "created": 1467155436449,  
  "data": {  
    "userId": "user123",  
    "accountId": "account123",  
    "unit": "USD",  
    "availableValue": 4500,  
    "resourceVersion": 1579030928001  
  }  
}

`coupon.created`

Sent whenever a new referral code is created.

{  
  "id": "31049u0194u2105",  
  "type": "coupon.created",  
  "tenantAlias": "AAA111BBB222DDD333",  
  "live": false,  
  "created": 1337001337,  
  "data": {  
    "code": "ABC123ABC",  
    "dateCreated": 123123123123,  
    "programId": "program1"  
  }  
}

`reward.created`

Sent whenever a new reward is created. Data is a single Reward Object that is returned from the List Rewards REST API Endpoint

{  
  "id": "577405e3e4b0cc57c1e2e687",  
  "type": "reward.created",  
  "tenantAlias": "aohgcctyskc0p",  
  "live": true,  
  "created": 1467221475167,  
  "data": {  
    "id": "577405e3e4b0cc57c1e2e684",  
    "type": "PCT_DISCOUNT",  
    "dateGiven": 1467221475151,  
    "dateExpires": 1475170275151,  
    "dateCancelled": null,  
    "accountId": "6UTR8OQZX0HE3QBP",  
    "userId": "56f2e6a9e4b08a1cbef6c561",  
    "cancellable": true,  
    "rewardSource": "FRIEND_SIGNUP",  
    "discountPercent": 15,  
    "unit": "%"  
  }  
}

`referral.started`

Sent whenever a new referral connection is successfully established.

{  
  "id": "5773073fe4b066c5cb171900",  
  "type": "referral.started",  
  "tenantAlias": "aohgcctyskc0p",  
  "live": true,  
  "created": 1467156287085,  
  "data": {  
    "id": "5773073ee4b066c5cb1718fc",  
    "referred": {  
      "id": "5773073ee4b08b14ab979fb8",  
      "accountId": "5773073ee4b08b14ab979fb8"  
    },  
    "referrer": {  
      "id": "577306eae4b08b14ab979f70",  
      "accountId": "577306eae4b08b14ab979f70"  
    },  
    "referralCodeUsed": "LORETTABURKE10",  
    "shareLinkUsed": "<http://ssqt.co/mPbcF5">,  
    "moderationStatus": "PENDING",  
    "dateReferralStarted": 1467156286882,  
    "dateConverted": null  
  }  
}

`referral.converted`

Sent whenever a referral is converted.

{  
  "id": "57731b5ee4b07320b5c0980a",  
  "type": "referral.converted",  
  "tenantAlias": "aohgcctyskc0p",  
  "live": true,  
  "created": 1467161438453,  
  "data": {  
    "id": "57731b43e4b07320b5c097ec",  
    "referred": {  
      "id": "5773073ee4b08b14ab979fb8",  
      "accountId": "5773073ee4b08b14ab979fb8"  
    },  
    "referrer": {  
      "id": "577306eae4b08b14ab979f70",  
      "accountId": "577306eae4b08b14ab979f70"  
    },  
    "referralCodeUsed": "LORETTABURKE10",  
    "shareLinkUsed": "<http://ssqt.co/mPbcF5">,  
    "moderationStatus": "PENDING",  
    "dateReferralStarted": 1467161411028,  
    "dateConverted": 1467161438415  
  }  
}

`export.created`

Sent whenever a data export is queued for creation.

{  
  "id": "57740ebae4b0cc57c1e2e8b9",  
  "type": "export.created",  
  "tenantAlias": "aohgcctyskc0p",  
  "live": true,  
  "created": 1467223738961,  
  "data": {  
    "id": "57740ebae4b0cc57c1e2e8b8",  
    "name": "Test Export Webhook",  
    "requester": "Hayward Erikson",  
    "status": "PENDING",  
    "dateCreated": 1467223738947,  
    "dateExpires": null,  
    "dateCompleted": null,  
    "type": "USER",  
    "outputFormat": "CSV",  
    "params": {  
      "createdSince": null,  
      "createdBefore": null,  
      "updatedSince": null,  
      "updatedBefore": null,  
      "createdOrUpdatedSince": null,  
      "createdOrUpdatedBefore": null  
    }  
  }  
}

`export.completed`

Sent whenever an export that was being generated has been completed and is ready to be downloaded.

{  
  "id": "57740ec5e4b034a7ceae80de",  
  "type": "export.completed",  
  "tenantAlias": "aohgcctyskc0p",  
  "live": true,  
  "created": 1467223749687,  
  "data": {  
    "id": "57740ebae4b0cc57c1e2e8b8",  
    "name": "Test Export Webhook",  
    "requester": "Hayward Erikson",  
    "status": "COMPLETED",  
    "dateCreated": 1467223738947,  
    "dateExpires": 1470247749304,  
    "dateCompleted": 1467223749304,  
    "type": "USER",  
    "outputFormat": "CSV",  
    "params": {  
      "createdSince": null,  
      "createdBefore": null,  
      "updatedSince": null,  
      "updatedBefore": null,  
      "createdOrUpdatedSince": null,  
      "createdOrUpdatedBefore": null  
    }  
  }  
}

`test`

Sent to test a subscription.

{  
  "id": "1337049u0194u2105",  
  "type": "test",  
  "tenantAlias": "AAA111BBB222DDD333",  
  "live": false,  
  "created": 1337001337,  
  "data": {  
    "endpointUrl": "<http://example.com/hook">,  
    "name": "Example"  
  }  
}

Webhook Management API Endpoints

Webhook events

Payloads

Webhook event details

user.created

⚠️Note:

user.reward.balance.changed

Eventual consistency

coupon.created

reward.created

referral.started

referral.converted

export.created

export.completed

test

`user.created`

⚠️
Note:

`coupon.created`

`reward.created`

`referral.started`

`referral.converted`

`export.created`

`export.completed`

`test`