Configuration

Please review the webhooks overview before continuing with the steps below.

Available Actions

Decide on an action you would like to subscribe to (i.e. shipment.created). You can view all available actions here:

curl 'https://api.channelape.io/rest/v1/webhook_actions' \
-H "apikey: ANON_KEY" \
-H "Authorization: Bearer YOUR_KEY"

Configurations

Decide which business you would like to receive webhooks for and were you want to send the events. Set the URL where you want to receive webhook events as the hook_consumer_url below.

Create the webhook with the call here:

curl -X POST 
'https://api.channelape.io/rest/v1/webhook_configurations' \
-H 'Content-Type: application/json' \
-H 'apikey: ANON_KEY' \
-H 'Authorization: Bearer YOUR_KEY' \
-d '{
  "business_id" : "0ba2563e-92fa-41e8-98e1-97361c3e608a",
  "hook_consumer_url" : "https://webhook.site/1ce3e263-2116-48f7-a57c-ea1c240499b7"
}'

Configuration Actions

Once you have a webhook endpoint configured for a business, you can subscribe it to one or many actions.

First find the webhook_configuration_id using this request to get all of the configurations for a business using the call here:

curl 'curl 'https://api.channelape.io/rest/v1/webhook_configurations?business_id=eq.YOUR_BUSINESS_ID' \' \
-H 'Content-Type: application/json' \
-H "apikey: ANON_KEY" \
-H "Authorization: Bearer YOUR_KEY"

Then subscribe the configuration to an action using the below call replacing the webhook_configuration_id with your value from the previous step using the call here:

curl -X POST 
'https://api.channelape.io/rest/v1/webhook_configuration_actions' \
-H 'Content-Type: application/json' \
-H "apikey: ANON_KEY" \
-H "Authorization: Bearer YOUR_KEY" \
-d '{
  "webhook_configuration_id" : "bdd307a8-8488-4f37-a5c2-da04e3d0d736",
  "action" : "shipment.updated.status",
  "capture_snapshot": false
}'

Capture Snapshots

Initially when webhooks launched, we captured the entire snapshot of the order as it was updated. However, this proved costly on larger objects, so to add a middle ground, we added a flag to actions that will only send the current state of the object as the webhook fires. Note that webhooks fire on a cron every minute, so if you have multiple updates in between minutes, you'd only see on model(you will still receive n number of webhooks though).

Large Webhooks

You'll notice that we default the producer_url to our service provider for handling webhooks. However, there is 300kb limit on these, so anything over that will go directly to the hook_consumer_url.

Portal

Once you configure the above you should be ready to receive webhook payloads for the actions specified at the given hook consumer url.

We expose a portal for you to debug delivery as well as inspect and replay past webhooks.

You can gain access to this portal for a few days with the call here:

curl -X POST 
'https://api.channelape.io/rest/v1/rpc/create_webhook_portal_magic_link' \
-H 'Content-Type: application/json' \
-H "apikey: ANON_KEY" \
-H "Authorization: Bearer YOUR_KEY" \
-d '{
  "business_id" : "bdd307a8-8488-4f37-a5c2-da04e3d0d736"
}'

tip

Review webhooks advanced to learn more about the capabilities of the portal.