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.

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.

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

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"]
    }
  }
}

Did this page help you?