Postbacks

Listen for events as a Partner in your PartnerStack instance as they occur.

Similar to Webhooks, Postbacks are notifications to an external service when events occur in the PartnerStack platform for your instance, such as reward creation. However, Postbacks are specific to Partners.

25362536

How do postbacks work?

Again, this works exactly like a webhook. There is an event and a subscribed endpoint that will be receiving the event. The endpoint must accept an HTTP POST request. For example, when an event, such as a vendor you are partnered with generates a reward for you, we will send an HTTP POST request to the subscribed endpoint you've configured. The payload will contain information regarding the event that occurred.

Registering a postback

Navigate to the Postback Settings page under https://dash.partnerstack.com/settings/postback. You can also access this page by going to your profile settings and then Postback.

Then create a new postback. The following fields are required:

  • Endpoint URL - The URL that we will call when an event occurs in the platform for your instance.
  • Name - The name of this postback. Use this field to describe the purpose of this postback.
  • Event Types - The types of events that this postback will be subscribed to. A postback can subscribe to multiple events.
16041604

Once created, you can verify that URL you provided can receive our events by sending a test event. Below is the test event payload:

{
  "event": "test",
  "data": {
    "message": "Test event sent!"   
  }
}

You're all set! You will now receive event information that you have subscribed to when they occur.

Postbacks you create can also be viewed, updated, or deleted by simply selecting the postback.

25302530

Events we support

Below are the following events we support for postbacks along with their sample payload:

Action Events

The following event types are available:

  • action_created - An Action related to your partnership with a vendor has been created.
  • action_updated - An Action related to your partnership with a vendor has been updated.

Data Fields:

FieldDescription
keyUnique identifier for the *Action.
typeThe type of action the Partner or Customer performed.
valueThe number of times the action was performed.
partnership_keyUnique identifier of your Partnership .
archivedBoolean value of whether the Action has been archived.
created_atThe creation date of the Action in epoch (ms).
updated_atThe last time the Action was updated in epoch (ms).
company.keyUnique identifier of the Company.
company.nameThe name of the Company.
customer.keyUnique identifier for the Customer.
customer.sub_idsA listof sub IDs used for tracking purposes for the Customer.
{
  "event": "action.created",
  "data": {
    "key": "act_M1VjnMQ4YIbVFY",
    "type": "post_created",
    "value": 1,
    "partnership_key": "part_zOoTHejddCMxJl",
    "archived": false,
    "created_at": 1623684855940,
    "updated_at": 1623684855940,
    "company": {
      "key": "co_1IfoLwRHJjObNrdv",
      "name": "IdeaAI",
    },
    "customer": {
      "key": "cus_1IfoLwRHJjObNrdv",
      "sub_ids": ["youtube"]
    }
  }
}

Customer Events

The following event types are available:

  • customer.created - A Customer related to your partnership with a vendor has been created.
  • customer.updated - A Customer related to your partnership with a vendor has been updated.
  • customer.deleted - A Customer related to your partnership with a vendor has been deleted.

Data Fields:

FieldDescription
keyUnique identifier for the Customer.
sub_idsA list of sub IDs used for tracking purposes for the Customer.
has_paidBoolean value of whether the Customer has paid.
partnership_keyUnique identifier of your Partnership .
created_atThe creation date of the Customer in epoch (ms).
updated_atThe last time the Customer was updated in epoch (ms).
company.keyUnique identifier of the Company.
company.nameThe name of the Company.
{
  "event": "customer.created",
  "data": {
    "key": "cus_1IfoLwRHJjObNrdv",
    "sub_ids": ["youtube"],
    "has_paid": true,
    "partnership_key": "part_zOoTHejddCMxJl",
    "created_at": 1623684855940,
    "updated_at": 1623684855940,
    "company": {
      "key": "co_1IfoLwRHJjObNrdv",
      "name": "IdeaAI",
    }
  }
}

Reward Events

The following event types are available:

  • reward.created - A Reward has been generated for you by a vendor you are partnered with.
  • reward.updated - A Reward for you has been updated by a vendor you are partnered with.

Data Fields:

FieldDescription
keyUnique identifier for the Reward.
descriptionThe description of the Reward generated.
amountThe amount of the Reward in cents (USD).
reward_statusThe status of the Reward. Can be one of:
hold,
pending,
approved,
declined,
paid
payment_statusIndicates whether the Reward can be withdrawn. Can be one of:
pending,
available,
withdrawn

It can also be null if the payment was declined.
payment_dateThe epoch timestamp (ms) for when the partner should be able to cash out the reward. Can be null when the reward is declined.
sourceThe source that generated this Reward. Can be one of:
transaction,
lead,
deal,
submission,
action,
bill,
asset,
order_item,
request,
bonus
partnership_keyUnique identifier of your Partnership .
created_atThe creation date of the Reward in epoch (ms).
updated_atThe last time the Reward was updated in epoch (ms).
company.keyUnique identifier of the Company.
company.nameThe name of the Company.
customer.keyUnique identifier for the Customer.
customer.sub_idsA list of sub IDs used for tracking purposes for the Customer.
{
  "event": "reward.created",
  "data": {
    "key": "rwrd_GWCpiWvW3ZekLe",
    "description": "$5 for every sign-up.",
    "amount": 5000,
    "reward_status": "paid",
    "payment_status": "withdrawn",
    "payment_date": 1624390897988,
    "source": "transaction",
    "partnership_key": "part_zOoTHejddCMxJl",
    "created_at": 1623684855940,
    "updated_at": 1623684855940,
    "company": {
      "key": "co_1IfoLwRHJjObNrdv",
      "name": "IdeaAI",
    },
    "customer": {
      "key": "cus_1IfoLwRHJjObNrdv",
      "sub_ids": ["youtube"]
    }
  }
}

Transaction Events

The following event types are available:

  • transaction.created - A Transaction related to your partnership with a vendor has been created.
  • transaction.updated - A Transaction related to your partnership with a vendor has been updated.

Data Fields:

FieldDescription
keyUnique identifier for the Transaction.
amountThe amount of the Transaction in cents for the specified currency.
amount_usdThe amount in USD cents of the Transaction.
currencyThe type of currency of the Transaction.
product_keyThe key of the product for the Transaction.
partnership_keyUnique identifier of your Partnership .
archivedBoolean value of whether the Transaction has been archived.
created_atThe creation date of the Transaction in epoch (ms).
updated_atThe last time the Transaction was updated in epoch (ms).
company.keyUnique identifier of the Company.
company.nameThe name of the Company.
customer.keyUnique identifier for the Customer.
customer.sub_idsA list of sub IDs used for tracking purposes for the Customer.
{
  "event": "transaction.created",
  "data": {
    "key": "tran_GWCpiWvW3ZekLe",
    "amount": 5000,
    "amount_usd": 5000,
    "currency": "USD",
    "product_key": "1-month",
    "partnership_key": "part_zOoTHejddCMxJl",
    "archived": false,
    "created_at": 1623684855940,
    "updated_at": 1623684855940,
    "company": {
      "key": "co_1IfoLwRHJjObNrdv",
      "name": "IdeaAI",
    },
    "customer": {
      "key": "cus_1IfoLwRHJjObNrdv",
      "sub_ids": ["youtube"]
    }
  }
}