Getting started with Marketplacer Webhooks

This guide takes you through how to:

  • Set up a test HTTP POST endpoint
  • Register a webhook in Marketplacer Admin
  • Invoke the webhook

Setup a test HTTP POST Endpoint

The webhook events generated by Marketplacer require a HTTP POST endpoint as the target destination. In a production environment, it would be the responsibility of the Information Consumer to provide this endpoint, however for the purposes of this tutorial, we’re going to set up a test endpoint using a, (free), tool called Pipedream.

Note: If you already have a HTTP endpoint that can receive POST requests via the internet, then you can choose to skip this section and move on to: Registering a Webhook

Following sign-up and login, (not shown here!), at: https://pipedream.com navigate to workflows:

Pipedream workflows


Select New

Pipedream workflows


Then select HTTP / Webhook from the list of available triggers:

Pipedream workflows


Choose the webhook type most suited to your needs, we’ll go with New Requests

Pipedream workflows


Accept the defaults on the next screen and select Create Source

Pipedream workflows


This should create a HTTP endpoint that’s available and listening for incoming HTTP POST (webhook event) requests. Make a note of the URL as we’ll be using that in the next section.

Pipedream workflows


Registering a Webhook

Webhooks can be registered at both the Seller and / or Marketplace level, in this guide we show you how to access webhook management from both:

  • The Seller Portal
  • The Admin (Operator) Portal

Aside from the different entry points, the process for managing webhooks is the same.


Webhooks from the Seller Portal

  • Login to the relevant Seller Portal
  • Select API & Integrations
  • Select Webhooks

Webhooks Configuration


This should then take you to Webhook Management, see below.

Webhooks from the Admin Portal

Login to Marketplacer Admin:

Marketplacer Admin


In the left hand menu, expand Configuration and select Webhooks:

Webhooks Configuration


This should then take you to Webhook Management, see below.

Webhook Management

Webhook Management is where you would come to:

  • Add new webhooks
  • Edit existing webhooks
  • Look at events generated on existing webhooks


Selecting New Webhook takes you to the webhook creation form as shown below:

Add a new webhook


These sections are described in more detail below:

Enabled

Self-explanatory really, but remember to tick if you want to generate webhooks - the default is un-ticked…

Type

Select from 1 of three types:

  • Invoice
  • Refund Request
  • Variant

In this example we’ll select the Invoice type.

Invoice Type Selected


URL

Use the URL of your HTTP POST endpoint, (we generated this using Pipedream in the last section):

Invoice Type Selected


GraphQL

You have 2 options here:

  1. Leave blank - we’ll send you a basic payload for the entity of your choosing
  2. Provide a GraphQL query - this allows you to tailor the payload returned - we describe this in more detail below


Providing a GraphQL Query

As we have selected the invoice as our entity for this example, the GraphQL query below shows not only how you can return fields directly on an invoice but also for entities related to invoice:

  • order
  • refundRequests
  • seller
  • shipment
  • lineItems

You’ll also note that we make use a variable called $id in order that we can dynamically supply the ID value for our Invoice:

query($id: ID!)
{
    node(id: $id){
        ... on Invoice{
            id
            status
            order 
            { 
                id 
                status
            } 
            refundRequests 
            { 
                cashAmountCents 
                invoice 
                { 
                    id 
                } 
            } 
            seller 
            { 
                id
                businessName 
            } 
            shipments 
            { 
                id 
                carrier 
                trackingLink 
                trackingNumber 
            } 
            lineItems 
            { 
                id 
                status 
            }
        }
    }
}

Note: A more detailed discussion on querying with GraphQL is outside the scope of this tutorial, for more information on the GraphQL query language, please refer to graphql.org

Adding this query to our webhook registration, you should see something similar to the following:


GraphQL Query


Headers

Again this is an optional field, if you have a need to provide any further headers you can do so here using the following as an example:

{"X-Test":"bfb demo"}

The Complete Registration

If you have followed the steps above, you should have something similar to this:

Completed Registration Form


Saving the webhook you should be returned to webhook management where you’ll see your registered webhook, be sure to check that it is enabled (the green tick):


Registered Webhook

Invoking the Webhook

As we have chosen an invoice as our entity, most “changes” to an invoice will invoke a webhook event, e.g.:

  • Invoice creation
  • Invoice payment status
  • Shipment status

So the simplest of these would be to create a new order (which will generate an associated invoice). We’ll use the Marketplacer storefront to do this as follows:

  • Browse for an item
  • Add item to cart
  • Enter customer details (or login if you have an account)
  • Enter payment details
  • Complete Order (Click Pay Now)

For the purposes of brevity we won’t detail each of these steps with a screenshot, instead jumping to just before completing the order:


Complete order


Click “Pay Now” to generate your order and over in Pipedream we should see some events come through:


Webhook Events


You’ll note that we get 2 events:

  1. Create
  2. Update (when we acknowledge payment)

You’ll also see that we get a JSON payload that matches the result of our GraphQL query.


Next Steps

The process for setting up webhooks for the other entity types is exactly the same, the only difference would be the GraphQL query should you choose to provide one.