Skip to content
Optima docs
ConsoleCampaignsJourneys

Webhook node

Call an external web address or a registered system from a journey, read the answer into the journey, and branch on whether it worked.

The Call system node makes an HTTP request to another system while a customer is moving through a journey: tell a CRM a customer reached a step, create a task for a call centre, ask a stock service whether an item is available. It can read fields from the answer into the journey, and branch on whether the call worked. In the node palette it is labelled Call system; the console and this page also call it a webhook.

Who uses it

Campaign creators build the node; integration specialists register the systems it can call. Changing the node needs campaign_editor, or another role your administrator has given access to this area — see Licences and roles. A registered system is created under Settings → Integrations → External systems.

Fields

How to call chooses between two modes.

FieldMeaningValid valuesDefault
How to callInline request: you type the request in the node. Fast for a one-off endpoint, but everything you type is stored in the journey definition in clear text. Registered system: a system you registered owns the request and holds the credentials; the node only supplies parameters.Inline request, Registered systemInline request

Inline request

FieldMeaningValid valuesDefault
URLThe address to call. Can be a personalization value.An absolute http:// or https:// address. Loopback (localhost) addresses are always refused, and private and cloud-metadata addresses are refused unless your platform operator allows them.None (required)
MethodThe HTTP method.GET, POST, PUT, PATCH, DELETEPOST
Timeout (seconds)How long to wait for an answer.1 to 6010
HeadersExtra request headers, as Header and Value rows. Values can be personalized.Name and value pairsNone
Body templateThe request body, written as a template over the profile (.Profile) and the journey's state (.Run.State). Use {{json .Run.State}} to embed the whole state as JSON. Empty sends no body.TextEmpty

Headers typed here are stored in clear text. For anything with a real credential (basic authentication, OAuth2, mutual TLS) register an external system instead.

Registered system

FieldMeaningValid valuesDefault
External systemThe system to call. Rotating its credentials never touches this journey.A system from Settings → Integrations → External systemsNone (required)
ParametersThe values the system asks for. Each is a template such as {{.Profile.Attributes.email}} or {{.Run.State.code}}, rendered before the system builds its request.One field per parameter the system declaresNone

Both modes

FieldMeaningValid valuesDefault
Consent purpose (optional)Skips the call for profiles without an active consent for this purpose. A system's own required purpose still applies.A purpose from your catalogueNone
Read from the response (optional)Lifts one JSON field of the answer into a journey state key, so a later condition can read it and message copy can print it. Each row is a run-state key and a $.path.in.response. A path that does not resolve leaves the key unset.Key and path pairsNone
Success when (optional)Decides what counts as a success."2xx", "any", or an expression over status, body and the mapped keys, for example outcome == "accepted""2xx"

The response status and body are stored in the journey's state under webhook:NODE. Keys you map must not start with the engine's own prefixes.

Branching on the result

Draw one unlabelled edge to continue whatever happens (it shows as always). To branch on the outcome, label both outgoing edges, one on_success and one on_error, by drawing them from the matching exit dot. Success when decides which one a run takes. When success is not satisfied, a node with labelled edges takes on_error; a node with only the unlabelled edge continues either way.

Test this request

Below the fields, Test this request renders the exact request the node would send (method, URL, headers and body), using the engine's own rules, so you can check it before saving.

FieldMeaning
ProfileA real profile to fill .Profile with, under your own acting purpose and PII level.
Run stateA JSON object that seeds .Run.State: what earlier nodes would have written by the time the run reaches here.

Render shows the headers and body without sending. Send it performs the real request, and the endpoint cannot tell it from a live one. It then shows the Response, what was Mapped into run state, and whether success_when is satisfied and which exit the node would take. If your environment withholds outbound calls, Send it says so and nothing is sent.

The test checks the node the way a save does. A success_when that does not compile against status, body and your response_mapping keys is refused with the same message, before anything is rendered or sent.

Actions

  • Add header, Add mapping and Add parameter add rows. Save the dialog, then the journey.
  • Test a whole journey without making real calls using Pre-flight: its simulation shows the request a call node would make and only calls out when you switch on Actually call action nodes.

Examples

Tell the CRM. Inline request, Method POST, URL https://crm.example.com/hooks/optima, Body template {"customer": "{{.Profile.ID}}", "state": {{json .Run.State}}}. One unlabelled edge continues.

Check stock before offering. A registered system Stock check, parameter sku = {{.Run.State.sku}}, Read from the response key in_stock = $.available, Success when in_stock == true. Label the two edges on_success (send the offer) and on_error (exit).

Common problems

  • The editor says Set a webhook URL starting with http:// or https://. Enter an absolute address.
  • The request is refused. Optima does not call addresses inside private networks unless your administrator has allowed them.
  • The call is skipped for some profiles. They have no active consent for the Consent purpose.
  • The branch always goes to on_error. Success when is not satisfied, for example because the endpoint answers 302 or 404, or the body reports a failure while the status is 200 (use an expression for that), or the expression refers to a key that was not mapped. Test the request and read the Response.
  • Save is refused with success_when does not compile. Success when is checked when you save. It may only use status, body and the keys under Read from the response, and it must answer true or false. Fix a misspelled key, or add the key under Read from the response.
  • A mapped key is empty. The path did not resolve, so the key is left unset.
  • Send it says this environment withholds execution. Real calls are switched off in this environment. Render still works.

On this page