Webhooks (External)
Last updated
Last updated
JourneyApps supports outgoing webhooks that allow remote endpoints to be called when data changes are made.
Webhooks can be configured for a specific model in your Data Model, which will then be triggered when certain conditions are met.
Webhooks are defined in the Data Model of your app, in OXIDE.
To define webhooks to be sent when a specific type of object is created or saved, add a <webhook/> element at the end of a <model/> definition.
Webhooks can be defined for integrating with internal JourneyApps systems, specifically CloudCode, or with external services.
All webhook requests include a signature that can be used to verify the authenticity without needing to configure any shared secrets.
The configuration options in the <webhook/> tag are as follows:
type=""
The type of webhook, this can be either ready or update. A ready webhook will only be triggered once for a specific object when the conditions are met. An update webhook will be triggered each time the object is saved and the conditions are met.
name=""
Mandatory name for the webhook.
receiver=""
action=""
The CloudCode task name, if the receiver was specified as "cloudcode".
Note: Only type="" and name="" are relevant for webhooks to external systems.
Example: External Webhook
In the example below, we trigger a request to http://requestb.in/1mwlqhx1 every time that an object of type resource is saved.
The relevant headers for the resulting POST request are as follows:
X-Journey-Signature-Rsa-Sha256-Key-Id
Webhook Verification 1
X-Journey-Signature-Rsa-Sha256
txho18dwBF2BNQpUdh6ji8govTy/kC cE6kBiYQg\ntTE/9uFS2OvRCy8yJa3 oT3HtdLMqjb2W7CLVlY\nctdenZnQH tLW7MRtM/KZYNP4h2dwbR/yAbeA\nh XPrWGGizSaSwH+tL6hjNmldvp3jMHi C2E8kK\nvz5z5BkQ0BSII2rLiVO3HX jg4SOlzw/VXMpv8g2\nFtCwaUOA2by kAm/LmPNY/nn2wtLR3rKOhleeA\noh 2CEWXM+cx05K01afbFV9oabjgLWXWc TmV\nu/c9ceeUd210SKudpIY3i7lma JWort8w1vXU5SS\ns+wx12KUGMMlDY mCgMWU0cPxP7KoelLaX+\nuUuw7JMg==
X-Journey-Signature
b1a6704741054a48363b4e02d89f7d6243b1adf54aa0fa4dd338c5d2949028b4
Content-Type
application/json
User-Agent
Journey/0.0.1 (Ruby)
(Purely informational)
The JSON body for the request is as follows:
Webhook definitions can optionally contain a number of field elements for specifying triggering conditions and embedded attachments or belongs-to objects. The webhook will only trigger once all conditions have been met, regardless of the type of webhook.
The configuration options for the field element are as follows:
name=""
The name of the field on which to operate.
required=""
If the field is required or not in order to trigger the webhook (true or false). Defaults to true.
embed=""
If the belongs-to related object or attachment should be embedded in the webhook request (true or false). Defaults to true.
state=""
Set state to uploaded if the attachment must already have been uploaded. Set state to present if the attachment need only exist but not necessarily yet be uploaded. Defaults to present.
In the example below, we trigger the event for the asset_ready webhook the first time that the asset_photo attachment field is set and uploaded and the user (belongs-to relationship) is set. The asset_photo attachment field is embedded in the webhook request.
Specify "cloudcode" if the webhook should trigger a CloudCode task. See the section for further details.
The values in sequence are large numbers, so make sure that you are using big ints / doubles / similar. Something like is required for JavaScript. Take care when testing with services such as requestbin, since they often truncate/round these values.
