Webhooks
Webhooks are user-defined HTTP callbacks triggered by an event. They allow a web-based application to respond in real time to something that’s happened on a different web-based application. They eliminate the need for polling and greatly facilitate decoupling, which makes your code simpler and easier to maintain over time.
Using the Crystallize App or PIM API, you can define webhooks that listen for and fire on specific events that occur within Crystallize (refer to our example repository for webhook-related sample queries). Webhooks can be used to automate processes such as emailing customers as their orders proceed through various stages of your fulfilment pipeline.
Crystallize offers webhooks for these categories of events:
- Catalogue item created/modified (products, documents, folders, topic maps, grids)
- Product, Document, or Folder added/removed from Flow stage
- Order created/modified
- Order fulfilment pipeline status changed
- Customer created/modified
- Price list created/modified
- Market created/modified
- Subscription contract created/modified
- Tenant copy started/finished/failed
You have the flexibility to respond to webhooks however you require. Crystallize webhook requests may use one of the following HTTP methods:
- GET
- PUT
- POST
- PATCH
- DELETE
You can optionally specify headers and a payload using a GraphQL query (mutations aren’t allowed in the payload). Note that header names will be converted and stored as lowercase (ex. Hello-Test will become hello-test). If you don’t specify a payload, the webhook endpoint will still have a default JSON payload containing all of the parameters available to such a query. If you specify a custom payload and also want the contents of the default payload, you can set the preserveDefaultPayload flag to true. For improved performance, it’s recommended to fetch all the data that your webhook endpoint may need in one go.
To test webhooks, we recommend using something like webhook.site or ngrok.
For added security, the requests sent by Crystallize webhooks are signed. It is your responsibility to verify these signatures.