Retailer Notification Configuration Document

The retailer notification configuration document is a model containing information regarding the handling of notifications for retailers identified by their respective client IDs. The document maps a given client ID to a document containing, in summary:

• A list of webhook configuration models, specifying:

  • which resource types the retailer is subscribed to in a given set of origins (if the retailer is subscribed to no origin in particular, no filter will be applied);
  • the webhook URIs to notify via a HTTP POST request;
  • optional custom headers the retailer can require in order to ensure the webhook notification is legitimate.

• A list of notification configuration models for transactional emails, specifying:

  • which buyer notification triggers the retailer should receive emails about;
  • which seller notification triggers the retailer should receive emails about;
  • the set of origins the retailer is subscribed to. Emails will only be sent if their origin is in the specified whitelist, if the whitelist is empty, or if the email notification message itself does not specify an origin.

• A list of notification configuration models for push notifications, specifying:

  • which buyer notification triggers the retailer should receive push notifications about;
  • which seller notification triggers the retailer should receive push notifications about;
  • the set of origins the retailer is subscribed to. Push notifications will only be sent if their origin is in the specified whitelist, if the whitelist is empty, or if the push notification message itself does not specify an origin.

Here is an example of a valid retailer notification config doc instance:

JSON

{
    // Set up notifications via webhook.
    // If both `triggers` and `origins` are met, a REST HTTP request will
    // be sent to the specified `addresses` with the provided `apiToken`.
    "webhookConfigs": [
        {
            // If at least one of these events are triggered, proceed to webhook notification.
            // Triggers must be comma-separated and are case-insensitive.
            "triggers": "BuyerCreated, BuyerUpdated, BuyerDeleted",
            // Filter based on notification origin, unless the notification message contains
            // no origin or this list is empty, in which case it will act as a catch-all.
            "origins": [
                "app"
            ],
            // The webhook addresses to notify if the filters for `triggers` and `origins` pass.
            "addresses": [
                {
                    // The webhook address name for easy identification on the front-end.
                    "name": "My Webhook",
                    // The webhook address URL to send an HTTP request to.
                    "value": "https://my-webhook.com"
                }
            ],
            // The secret API key to send to the provided webhooks as
            // a X-API-KEY custom header in order to ensure the request
            // is coming from our side. The retailer should keep this key
            // private and not share it with anyone.
            "apiToken": "GVY7SKcrj34sd9Yg"
        }
    ],
    // Set up filters for email notifications for buyers and sellers associated with the retailer.
    "transactionalEmailConfigs": [
        {
            // Set up email notifications for buyers associated with the retailer.
            "buyerTriggers": [
                {
                    // If at least one of these events are triggered, proceed to email notification.
                    // Triggers must be comma-separated and are case-insensitive.
                    "triggers": "OrderCreated, OrderDelivered, OrderDispatched, OrderFinalized, OrderSeparated",
                    // Filter based on notification origin, unless the notification message contains
                    // no origin or this list is empty, in which case it will act as a catch-all.
                    "origins": [
                        "app"
                    ]
                }
            ],
            // Set up email notifications for sellers associated with the retailer.
            "sellerTriggers": [
                {
                    // If at least one of these events are triggered, proceed to email notification.
                    // Triggers must be comma-separated and are case-insensitive.
                    "triggers": "OrderCreated, OrderDelivered, OrderDispatched, OrderFinalized, OrderSeparated",
                    // Filter based on notification origin, unless the notification message contains
                    // no origin or this list is empty, in which case it will act as a catch-all.
                    "origins": [
                        "app"
                    ]
                }
            ]
        }
    ]
}