/events

Last modified December 11, 2017

Webhook events

Typically events are received by server webhooks, but API calls can also be used to retrieve previous webhook events. Events are either processed or unprocessed, depending on whether your webhook endpoint has acknowledged handling of the event. To learn more about acknowledging events see Webhooks.

The webhooks system generates the event contents at the time of each transaction, subscription, or other activity.  If you do not subscribe to webhooks, no webhook events are generated. Therefore, anything that happens while you do not have a webhook configuration for your Store will not have a webhook event generated, and so details of that activity will not be retrievable via the /events endpoint - even if you set up a webhook configuration after-the-fact.

For example, suppose the following are true:

  • Your Store goes live on Sunday and you do not subscribe to the order.completed webhook event.
  • On Monday a customer places an order.
  • On Tuesday, you subscribe to the order.completed event.
  • On Wednesday, a second customer places an order.

In this example, you would be able to retrieve Tuesday's order via /events, but even after you subscribe to order.completed, a call to /events would not return an order.completed event for Monday's transaction, because at the time of the transaction, there was no subscription to order.completed and so no event was generated.

You could, however, retrieve the details of Monday's order via the /orders endpoint - which does not rely on webhook event generation.

Certain modifiers are required when making a GET request to the /events endpoint of the API. Requests must include either the begin modifier to specify the unix date of the first event to be returned, or else the days modifier to specify the number of prior days' worth of events to be returned. In either case, the API will not return items more than 30 days old. Therefore, if you specify a begin date, it must be no more than 30 days past. Likewise, the number of days specified using the days parameter must not be greater than 30.

Note

Currently, only events posted to the topmost webhook configuration in your Dashboard (as shown under Integrations → Webhooks) can be accessed or updated via the /events endpoint of the API.

  Click here for an illustrated example

example of the Webhooks tab of the Integrations menu


Modifiers

  • ?days=5 - Events from last 5 days.
  • ?begin=unixtime&end=unixtime

Limited to 25 results returned. Results will contain a "more" attribute if there are more results beyond 25. To page to additional results the timestamp of the nearest event should be fed into begin / end (narrowing the timeframe).

Get multiple events

Get processed/acknowledged events

GET /events/processed?days=5

Get unprocessed events

GET /events/unprocessed?begin=1490655069974

The response structure is nearly identical to the structure of Webhooks, except the reponse will include a type indicator that identifies the event type (e.g. order.canceled).

Example response
{
  "action": "events.get",
  "result": "success",
  "page": null,
  "limit": null,
  "nextPage": null,
  "total": 0,
  "events": [
    {
      "id": "_72l0mpyTemSa29zpQoMIg",
      "processed": true,
      "created": 1487897414414,
      "type": "account.created",
      "live": true,
      "data": {
        "id": "DFTDIJEKS06lBQBp31lVAw",
        "account": "DFTDIJEKS06lBQBp31lVAw",
        "contact": {
          "first": "John",
          "last": "Doe",
          "email": "jdoe@fastspring.com",
          "company": null,
          "phone": null
        },
        "language": "en",
        "country": "US",
        "lookup": {
          "global": "2-LEckNbTzi4vdskEvxM2A"
        },
        "url": "https://furiousfalcon.onfastspring.com/account"
      },
      "event": "_72l0mpyTemSa29zpQoMIg"
    },
    {
      "id": "ok2KdevXTBeG548LU8ZXWw",
      "processed": true,
      "created": 1487897415756,
      "type": "payoutEntry.created",
      "live": false,
      "data": {
        "orderId": "76OpTgwCRpGdr9_lV_Eygw",
        "reference": "FUR170224-4235-32124",
        "live": false,
        "order": "76OpTgwCRpGdr9_lV_Eygw",
        "account": "DFTDIJEKS06lBQBp31lVAw",
        "subscriptions": [],
        "subtractions": {
          "tax": {
            "currency": "USD",
            "amount": 0,
            "percentage": 0
          },
          "fastspring": {
            "currency": "USD",
            "amount": 0.8856,
            "percentage": 8.9
          }
        },
        "payouts": [
          {
            "payee": "furiousfalcon",
            "currency": "USD",
            "payout": "9.06",
            "subtotal": 9.06,
            "total": "9.95"
          }
        ]
      },
      "event": "ok2KdevXTBeG548LU8ZXWw"
    },
    {
      "id": "pJODKqWNR0CuAKsda5Ft4w",
      "processed": true,
      "created": 1487897416589,
      "type": "order.completed",
      "live": false,
      "data": {
        "order": "76OpTgwCRpGdr9_lV_Eygw",
        "id": "76OpTgwCRpGdr9_lV_Eygw",
        "reference": "FUR170224-4235-32124",
        "buyerReference": null,
        "completed": true,
        "changed": 1487897415721,
        "changedValue": 1487897415721,
        "changedInSeconds": 1487897415,
        "changedDisplay": "2/24/17",
        "language": "en",
        "live": false,
        "currency": "USD",
        "payoutCurrency": "USD",
        "invoiceUrl": "https://furiousfalcon.onfastspring.com/account/order/FUR170224-4235-32124/invoice",
        "account": "DFTDIJEKS06lBQBp31lVAw",
        "total": 9.95,
        "totalDisplay": "$9.95",
        "totalInPayoutCurrency": 9.95,
        "totalInPayoutCurrencyDisplay": "$9.95",
        "tax": 0,
        "taxDisplay": "$0.00",
        "taxInPayoutCurrency": 0,
        "taxInPayoutCurrencyDisplay": "$0.00",
        "subtotal": 9.95,
        "subtotalDisplay": "$9.95",
        "subtotalInPayoutCurrency": 9.95,
        "subtotalInPayoutCurrencyDisplay": "$9.95",
        "discount": 0,
        "discountDisplay": "$0.00",
        "discountInPayoutCurrency": 0,
        "discountInPayoutCurrencyDisplay": "$0.00",
        "discountWithTax": 0,
        "discountWithTaxDisplay": "$0.00",
        "discountWithTaxInPayoutCurrency": 0,
        "discountWithTaxInPayoutCurrencyDisplay": "$0.00",
        "billDescriptor": "FS* fsprg.com",
        "payment": {
          "type": "test",
          "cardEnding": "4242"
        },
        "customer": {
          "first": "John",
          "last": "Doe",
          "email": "jdoe@fastspring.com",
          "company": null,
          "phone": null
        },
        "address": {
          "postalCode": "93105",
          "country": "US",
          "display": "93105, US"
        },
        "notes": [],
        "items": [
          {
            "product": "falcon",
            "quantity": 1,
            "display": "Furious Falcon",
            "sku": "falcon6abc123",
            "subtotal": 9.95,
            "subtotalDisplay": "$9.95",
            "subtotalInPayoutCurrency": 9.95,
            "subtotalInPayoutCurrencyDisplay": "$9.95",
            "discount": 0,
            "discountDisplay": "$0.00",
            "discountInPayoutCurrency": 0,
            "discountInPayoutCurrencyDisplay": "$0.00",
            "fulfillments": {
              "falcon_license_0": [
                {
                  "license": "Falcon-kLeEuksTu4UZXr5fT0Xb",
                  "display": "License Key",
                  "type": "license"
                }
              ],
              "falcon_file_0": [
                {
                  "display": "Falcon.exe",
                  "size": 5769,
                  "file": "https://furiousfalcon.onfastspring.com/account/file/FUR170224-4235-14140F",
                  "type": "file"
                }
              ],
              "instructions": "<p>Thank you for purchasing <em>Falcon</em>. To register, please launch the trial version and select <strong>Help</strong> | <strong>Register Falcon</strong>. Then, copy and paste the license key above into the <strong>License Key</strong> field and click <strong>Submit</strong>.</p>"
            }
          }
        ]
      },
      "event": "pJODKqWNR0CuAKsda5Ft4w"
    }
  ],
  "more": true
}



Possible Error Response Example
// No begin or days specified
{
  "action": "events.get",
  "result": "error",
  "error": {
    "begin": "Begin required."
  }
}


 
// Begin or days older than 30 days
{
  "action": "events.get",
  "result": "error",
  "error": {
    "begin": "Begin must be after '1488061077706' (Sat Feb 25 22:17:57 UTC 2017)."
  }
}


 
// Begin time later than end time
{
  "action": "events.get",
  "result": "error",
  "error": {
    "begin": "Begin must be less than end."
  }

}


 
// Unparseable values
{
  "action": "events.get",
  "result": "error",
  "error": {
    "begin": "Can not parse begin",
    "end": "Can not parse end."

    "days": "Can not parse days."
  }

}



Updating a single event

POST /events/{id}
Request Example
{
	"processed":true
}