Webhooks Integration

Webhooks are automated messages sent from applications in response to specific events.

Once your star profile is approved, we can enable webhooks upon request.

• You can specify your webhook endpoint in your Profile Settings.
• Once set up, you will start receiving POST requests as described in the section below.

Receiving events

Find X-SubscribeStar-Signature in the headers:

content-length: 653
connection: close
x-subscribestar-requestid: 2a26f9ba-5739-4fc3-b454-011c8526f138
x-subscribestar-timestamp: 1573226731
x-subscribestar-signature: db9cc60908e6d3c1b912730bff9795cd
host: webhook.site
user-agent: SubscribeStar Webhooks API
accept: */*
accept-encoding: gzip;q=1.0, deflate;q=0.6, identity;q=0.3
content-type: application/json

Then compare signature with the HEX digest of MD5 HMAC signed request body (the JSON string you receive from us) using your webhook's secret:

request.headers['X-SubscribeStar-Signature'] == OpenSSL::HMAC.hexdigest("MD5", secret, request.body)

Where secret is taken from your Profile Settings -> Webhooks section on the site. Request body is a JSON string.

Event Ordering

We do not guarantee that webhook events will always arrive in the correct order, though most events will likely be delivered sequentially. Network delays, failures, and retries may occasionally disrupt the order of delivery.

To ensure accurate processing, you can:

• Query the GraphQL API to retrieve the current state of a subscription or payment for the most up-to-date information.
• Use timestamp to sort events in the correct order.

Retries

If a webhook event cannot be delivered to your service, we will automatically retry sending it using an exponential backoff strategy. The retry intervals are as follows:

• 5 minutes
• 25 minutes
• 125 minutes (~2 hours)
• 625 minutes (~10.5 hours)

It is your responsibility to handle these retried events correctly. Each request includes an attempt attribute. If attempt is greater than 1, it means the initial HTTP request failed, and the same event is being resent.

Event types

Events contain two types of payload: subscription or payment (see below, payload key is event)

Subscription events

• email_shared
• email_unshared
• new_subscription
• recurring_pledge_decreased
• recurring_pledge_increased
• shipping_address_shared
• shipping_address_unshared
• subscription_billing_failed
• subscription_cancelled
• subscription_restored

Note on subscription_restored event:

In some circumstances (for example when payment fails) subscription will be restored, but not paid (it won't be extended and user will not be able to see the content). It is advised to get value of paidUntil from GraphQL API after this webhook event is received.

Example payload

{
  "payload": {
    "subscription": {
      "id": 10059451,
      "tier_id": 129388,                      # Unique identifier of the tier (same across all subscribers in the current tier)
      "cost": 10000,                          # ALWAYS IN CENTS (IN THIS CASE == $100.00)
      "last_payment_amount": 10000,           # CAN BE NULL OR NOT EQUAL TO SUBSCRIPTION PRICE IN CASE IF THE LAST PAYMENT IS UNDER REVIEW OR TIER HAS BEEN DOWNGRADED!
      "last_payment_settlement_amount": 10000, # CAN BE NULL OR NOT EQUAL TO SUBSCRIPTION PRICE IN CASE IF THE LAST PAYMENT IS UNDER REVIEW OR TIER HAS BEEN DOWNGRADED!
      "subscriber_id": 91953,
      "created_at_timestamp": 1573138322,
      "charged_at_timestamp": 1573138322,
      "extended_at_timestamp": 1573138322,     # THE DATE FROM WHICH WE COUNT NEXT RECURRING BILLING DATE (USUALLY EQUAL TO CHARGED_AT)
      "profile_id": 1,                         # YOUR STAR PROFILE ID
      "billing_failed": false,
      "billing_failed_at_timestamp": null,
      "cancelled": false,
      "cancelled_at_timestamp": null,
      "paused": false,
      "paused_at_timestamp": null,
      "restored_at": null,
      "trusted": false                         # PASSED TRUSTED PERIOD (SEE PROFILE SETTINGS)
    },
    "subscriber": {
      "email": "[email protected]",
      "nickname": "John Doe",
      "id": 91953
    }
  },
  "event": "new_subscription",                 # CAN BE: "email_shared", "email_unshared", "shipping_address_shared", "shipping_address_unshared", "recurring_pledge_increased", "recurring_pledge_decreased", "subscription_billing_failed", "new_subscription", "subscription_cancelled", "subscription_restored"
  "attempt": 1,                                # Number of attempts. Indicates retried submission if greater than 1.
  "project": "subscribestar",
  "timestamp": 1573138322
}

Payment events

• payment_disputed
• payment_succeed

Example payload

{
  "payload": {
    "payment": {
      "id": 1239168,
      "amount": 10000,
      "settlement_amount": 9820,                    # HOW MUCH STAR EARNS FROM THIS TRANSACTION
      "authorized_at_timestamp": 1573138322,        # ALWAYS RELY ON THIS DATE OF THE ACTUAL TRANSACTION
      "captured_at_timestamp": 0,
      "subscriber_id": 91953,
      "subscription_id": 59451,
      "tip_id": null,                              # NOT NULL IF TIP
      "comment": "Thank you!",                     # A USER MESSAGE FROM THE TIPPING FORM
      "profile_id": 1,
      "type": "subscription_fee"                   # CAN BE: "subscription_fee", "contribution", "tip"
    },
    "pledger": {
      "email": "[email protected]",
      "nickname": "John Doe",
      "id": 91953,
      "pledger_type": "subscriber"
    }
  },
  "event": "payment_succeed",                      # CAN BE: "payment_disputed", "payment_succeed"
  "attempt": 1,                                    # Number of attempts. Indicates retried submission if greater than 1.
  "project": "subscribestar",
  "timestamp": 1573138672

Troubleshooting

Please test it out using Webhook site before going fully live.