Support Center

Outbound Webhooks

Outbound Webhooks allow your application to receive information about events as they occur within catalog360. You can configure and test Outbound Webhooks using the Webhooks settings page in your account.

Outbound Webhook URLs should be set up to accept, at a minimum, POST requests. When you provide the URL where you want catalog360 to POST the data for events, we'll do a quick check that the URL exists by using a HEAD request (not POST).

If the URL doesn't exist or returns something other than a 200 HTTP response to the HEAD request, catalog360 will fallback and attempt a POST request. In this case, the events field will be an empty array, and the POST will be signed with a generic key (with the value 'test-webhook').

Configure Outbound Webhook URLs

Add a new Webhook

To add a new Webhook using the catalog360 application:

  1. Navigate to Settings in your catalog360 account.
  2. Click Webhooks.
  3. Click + Add a Webhook at the top of the page.
  4. Add your Webhook URL under Post To URL.
  5. Give your Webhook an optional description under Description.
  6. Choose the catalog360 events you want to sent to the Webhook URL (for example, when a report is generated, etc.).
  7. Click Save.

Event Classes

Webhooks can be triggered by several classes of events:

Event Class Payload Class Description
assetitem_created assetitem Asset Created
Triggered upon the creation of an Asset
assetitem_split assetitem Asset Split
Triggered upon the split of a grouped Asset into separately managed Assets
assetitem_updated assetitem Asset Updated
Triggered upon an update to an Asset
purchaseorder_created purchaseorder Purchase Order Created
Triggered upon the creation to a Purchase Order
purchaseorder_updated purchaseorder Purchase Order Updated
Triggered upon an update to a Purchase Order
reportjob_updated reportjob Report Job Complete
Triggered upon completion of a Report job
shipment_created shipment Shipment Created
Triggered upon the creation of a Shipment
shipment_updated shipment Shipment Updated
Triggered upon an update of a Shipment
task_completed task Task Completed
Triggered upon the completion of a Task
task_created task Task Created
Triggered upon the creation of a Task
task_updated task Task Updated
Triggered upon an update to a Task

Payloads

Webhooks receive payloads in JSON data format (Content Type: application/json). Every catalog360 Webhook uses the same general data format, regardless of the event class.

The Webhook request is a standard POST with the body of the request containing the JSON-formatted data.

Inside each request the events field contains an array of Webhook events, up to a maximum of 100 events. Each element in the array is a single event. 

Each Webhook event contains details of the event_class and payload_class to distinguish the different event types and the contents of the payload field.

For update events the payload field contains old and new fields which provide the data prior to and after the event. In the case of new records only the new field would be present in the payload, whereas for deletions only the old field is provided.

Payload Class Description
envelope Webhook Envelope - wraps all payloads
alert Alert
assetitem Asset Item
attachment Attachment
attribute Attribute
identity Identity
purchaseinvoice Purchase Invoice
purchaseorder Purchase Order
reportjob Report Job
shipment Shipment
task Task

Verifying Webhook Requests

catalog360 signs Webhook requests so you can (optionally) verify that requests are generated by us and not a third-party pretending to be catalog360. If your application exposes sensitive data, you may want to be sure the requests are coming from catalog360. This isn't required, but offers an additional layer of verification.

Signature Verification

catalog360 includes an additional HTTP header with webhook POST requests, X-C360-Signature, which will contain the signature for the request. To verify a Webhook request, generate a signature using the same key that catalog360 uses and compare that to the value of the X-C360-Signature header.

Get your Webhook security key

When you create a Webhook, a security key is automatically generated. You can also view and reset the security key from the Webhooks page in your account, in the Security Key field. 

Generate a Signature

In your code that receives or processes Webhook requests:

  1. Take the string containing the entire body of the request which is a valid JSON document
  2. Hash the resulting string using UTF-8 encoding with HMAC-SHA256, using your Webhook's security key to generate a binary signature.
  3. Base64 encode the binary signature
  4. Compare the binary signature that you generated to the signature provided in the X-C360-Signature HTTP header.

Note: Some HMAC implementations can generate either a binary or hexadecimal signature. catalog360 generates a binary signature and then Base64-encodes it; using a hexadecimal signature will not work.

Example implementations

Please refer to Examples of creating base64 hashes using HMAC SHA256 in different languages for example implementations of this signature generation and verification method.

Other Considerations

You can reset a Webhook's security key at any time. catalog360 will immediately begin using the new key to sign requests. To ensure that you don't lose any Webhook events between the time you reset your key and when you update your application to start using that new key, your Webhook processor should reject batches with failed signatures with a non-200 status code. catalog360 will retry later, which will give you time to update your application with the new key.

Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request

Comments

Powered by Zendesk