Create an integration

Create the webhook itself

Click Integrations → Integration Setup → Create Integration

Pick the Webhook Integration preset

Name your integration

Use a descriptive name so you’ll know what it does at a glance — like Shopify Order Sync or Zendesk Ticket Webhooks.

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 — the usual setup when one integration covers many different methods. Less typing, fewer typos, and if the base ever changes, you update it in one place instead of touching every webhook.

Example: For example, Maestra Platform’s own API uses https://api.maestra.io/v3/operations/ as the root. You set that once on the integration, and each webhook just adds the part that’s unique to its method.\

Set a request rate limit (optional)

If the receiving service has a rate cap, set the max requests per second here. Every webhook in this integration counts toward the same limit.

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

Add the headers your service needs. The two you’ll almost always set are Authorization (your API key or token) and Content-Type (usually application/json).

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

Click Create to save the integration.

Add a new webhook

You can create a webhook from one of two places — both end up in the same editor.

• From webhook integration point
• From webhooks list

Continue the setup you started in Part 1 — on the webhook integration page, click Create.

Go to Integrations → Webhooks → Create and pick the integration this webhook belongs to.

Fill in the basics

Field	What it’s for
Name	Use a descriptive name so you’ll know what it does at a glance.
System name	A unique ID used to reference this webhook’s response.
Description	Optional — fill in only if needed.
Method	GET, POST, PUT, PATCH, or DELETE — whatever the receiving service expects.
Root URL	This URL is inherited from the webhook integration — it’s shared by every webhook added to that integration.
URL	The path that gets appended to the root URL from your integration. Leave blank if the webhook integration point already has the full URL.
Overview 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