Postbacks

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.

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/postbacks. 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.

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.

Events we support

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

Action Events
Customer Events
Reward Events
Transaction Events

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:

Field	Description
`key`	Unique identifier for the *Action.
`type`	The type of action the Partner or Customer performed.
`value`	The number of times the action was performed.
`partnership_key`	Unique identifier of your Partnership .
`archived`	Boolean value of whether the Action has been archived.
`created_at`	The creation date of the Action in epoch (ms).
`updated_at`	The last time the Action was updated in epoch (ms).
`company.key`	Unique identifier of the Company.
`company.name`	The name of the Company.
`customer.key`	Unique identifier for the Customer.
`customer.sub_ids`	A 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:

Field	Description
`key`	Unique identifier for the Customer.
`sub_ids`	A list of sub IDs used for tracking purposes for the Customer.
`has_paid`	Boolean value of whether the Customer has paid.
`partnership_key`	Unique identifier of your Partnership .
`created_at`	The creation date of the Customer in epoch (ms).
`updated_at`	The last time the Customer was updated in epoch (ms).
`company.key`	Unique identifier of the Company.
`company.name`	The 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:

Field	Description
`key`	Unique identifier for the Reward.
`description`	The description of the Reward generated.
`amount`	The amount of the Reward in cents (USD).
`reward_status`	The status of the Reward. Can be one of: `hold`, `pending`, `approved`, `declined`, `paid`
`payment_status`	Indicates whether the Reward can be withdrawn. Can be one of: `pending`, `available`, `withdrawn` It can also be `null` if the payment was `declined`.
`payment_date`	The epoch timestamp (ms) for when the partner should be able to cash out the reward. Can be null when the reward is declined.
`source`	The source that generated this Reward. Can be one of: `transaction`, `lead`, `deal`, `submission`, `action`, `bill`, `asset`, `order_item`, `request`, `bonus`
`partnership_key`	Unique identifier of your Partnership .
`created_at`	The creation date of the Reward in epoch (ms).
`updated_at`	The last time the Reward was updated in epoch (ms).
`company.key`	Unique identifier of the Company.
`company.name`	The name of the Company.
`customer.key`	Unique identifier for the Customer.
`customer.sub_ids`	A 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:

Field	Description
`key`	Unique identifier for the Transaction.
`amount`	The amount of the Transaction in cents for the specified currency.
`amount_usd`	The amount in USD cents of the Transaction.
`currency`	The type of currency of the Transaction.
`product_key`	The key of the product for the Transaction.
`partnership_key`	Unique identifier of your Partnership .
`archived`	Boolean value of whether the Transaction has been archived.
`created_at`	The creation date of the Transaction in epoch (ms).
`updated_at`	The last time the Transaction was updated in epoch (ms).
`company.key`	Unique identifier of the Company.
`company.name`	The name of the Company.
`customer.key`	Unique identifier for the Customer.
`customer.sub_ids`	A 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"]
    }
  }
}