Create an integration

Create the webhook itself

Open Integrations and click Add Integration

Pick the Webhook Integration preset

Name your integration

Set the root URL

This is the base URL all webhooks in this integration will share. You can either:

• Put the full URL here and leave the path blank on individual webhooks, or
• Put only the root here and let each webhook add its own path.

Example: Maestra’s own API uses https://api.maestra.io/v3/operations/ as a root. You’d set that once on the integration, then each webhook only needs to add the specific operation ID.

Set a request rate limit (optional)

If the receiving service has a rate cap, set the max requests per second here. All webhooks in this integration share this budget.

The actual rate can vary slightly due to network delays. Set the limit a little below what the service can handle to stay safely under the cap.

Add headers

Headers that apply to every webhook in this integration go here. The most common ones:

Header	Purpose
Authorization	API key, bearer token, or basic auth credentials
Content-Type	Usually application/json for modern APIs
Custom headers	Anything else the receiving service requires

Mark any header containing a token or secret as private. Teammates without integration access won’t be able to see the value when they’re building webhooks.

Save

Your integration is now ready, and you can start adding webhooks to it.

Add a new webhook

Open it from the integration page, or go to Integrations → Webhooks.

Fill in the basics

Field	What it’s for
Name	What teammates will see in the flow builder and campaigns list.
System name	A unique ID used to reference this webhook’s response. Use lowercase and hyphens, e.g. shopify-create-order.
Description	Optional. Drop a sentence here so future-you remembers why this exists.
Method	GET, POST, PUT, PATCH, or DELETE — whatever the receiving service expects.
URL	The path that gets appended to the root URL from your integration. Leave blank if the integration already has the full URL.
URL preview	Shows the full assembled URL. Read-only — just for sanity-checking.

Add an idempotency key (recommended)

By default, a webhook is sent once. If the receiving service returns a 5xx or 429 error, the request is gone.Adding an idempotency key tells Maestra Platform to safely retry — up to 3 times over 6 minutes — without the receiving service treating the retries as new, duplicate events.Use the template variable:

${WebhookRequest.TransactionalId}

You can put it in the URL, a header, or the request body. Where it goes depends on what the receiving service expects.

Check your service’s API docs before adding this. Some services expect a specific parameter name (Idempotency-Key, request_id, etc.) or a particular format. If the service doesn’t recognize it, you won’t get retry protection.

Example: adding it to the URL as a query parameter

Append it after a ?:If the URL already has query parameters, use & instead:

Example: adding it as a header

Many APIs (Stripe-style) expect it as a header like Idempotency-Key: ${WebhookRequest.TransactionalId}.

Example: adding it to the request body

Drop it into your JSON payload as a field the receiving service expects, e.g. "request_id": "${WebhookRequest.TransactionalId}".

Set webhook-specific headers

Headers from the integration are inherited automatically. You can:

• Turn off an inherited header by unchecking Use.
• Add extra headers that only apply to this webhook.

Both inherited and webhook-specific headers go out with the request.In the example above, the final headers sent are:

Content-Type: application/json
webhookHeader: test

Build the request body

Drop in a JSON payload and pull in customer data using dynamic parameters from the message template engine.You can use:

• Variables like ${customer.email} or ${order.totalPrice}
• Conditionals with if / else if / end if
• Loops with for / end for — handy for line items in an order

The right-hand sidebar has the full variable picker.

Capture the response (optional)

Save