Calling a Webhook from a Trigger

Updated

Note: This article is technical, so we recommend involving someone with the right technical expertise. If you have any questions, contact us at support@azumuta.com.

A webhook trigger notifies another system as soon as something happens in Azumuta, for example when a product order is completed or an issue is reported. Use it instead of polling the REST API. Azumuta sends only the data of that event, at the moment it occurs. For the broader ERP pattern, see ERP Integration.

This article explains how to configure a Call a webhook trigger: where to set it up, which attributes to fill in, what Azumuta sends to your endpoint, what happens when the call fails, and how to check and retry runs.

Add a webhook trigger

  1. Click Settings under Management.
  2. Click Triggers under Integrations.
  3. Click Add trigger (the yellow plus button).
  4. Fill out the fields described below.
  5. When you’re done, click Add.

Scope, What and When

Select these first:

  • Scope: What the trigger applies to, such as all product orders, an article category, selected audit work instructions or an improvement board.
  • What: Select Call a webhook.
  • When: The event that calls the webhook, for example When a product order is finished or When an audit is finished.

The events per scope are listed in these articles:

After creation, you can edit or delete the trigger, and review usage history.

Attributes

After you select What and When, the Attributes section shows the webhook options:

  • Endpoint: The HTTPS URL Azumuta will call (placeholder starts with https://). This endpoint must be accessible from the Azumuta servers.
  • Method: GET, POST, PUT or PATCH. The default is GET.
  • Payload: Shown for every method except GET. Enter the custom body content here. You can use parameters in this field.
  • Authentication: How Azumuta identifies itself to your endpoint. See Authentication.
  • Request timeout: How many seconds Azumuta waits for a response before the attempt counts as failed. Enter a value from 1 to 300. Leave it empty to use the default of 30 seconds.
  • Retry automatically when the webhook fails: Switch on to retry a failed call. See Retry failed calls.

Authentication

Select how Azumuta identifies itself to your endpoint. New triggers start on None.

  • None: Azumuta sends no credentials.
  • Header: Azumuta sends one header with every call. Type the Header name (for example X-API-Key), then choose the value: Custom value (a secret you type) or API key from device (the key of an Api Device). The header names User-Agent, Origin and Content-Type are reserved.
  • Basic: Azumuta sends a username and password using HTTP Basic authentication.
  • OAuth client credentials: Azumuta first requests an access token and sends it with the call. Fill in the Token URL (it must be an HTTPS address), Client ID, Client secret and, if your provider needs one, Scope.

A secret you enter (a custom header value, a password or a client secret) is saved securely. Afterwards the field only shows ******, never the saved value. Changing the webhook URL clears the saved secret, and for OAuth so does changing the token URL, so you have to enter it again.

What Azumuta sends

Azumuta sends event-specific fields with every call:

Scope Typical fields
Product orders identifier (product order number), and when applicable workinstructionId and recordingId
Issues issueId, issueNumber (and for some events, related column/action fields)
Audits recordingId, workinstructionId, and related audit fields such as auditNumber

How those fields are delivered depends on the method:

  • GET: Fields are added as URL query parameters.
  • POST, PUT and PATCH: Fields are sent as JSON in the request body. If you configured a custom Payload, that content is nested under the key payload in the JSON body, next to the event fields above.

Every call also carries these headers, so your system can recognize the call and spot a repeat:

Header Value
X-Azumuta-Trigger-Run-Id The ID of the trigger run. It stays the same for every attempt of the same run.
X-Azumuta-Trigger-Id The ID of the trigger.
X-Azumuta-Webhook-Attempt The attempt number. The first call is 1, the first retry is 2, and so on.

Retry failed calls

A call counts as failed when your endpoint answers with an error status (anything other than a 2xx status), does not answer within the Request timeout, or cannot be reached. A failed call is recorded as a failed run, so a failing integration shows as failing in the run history.

Without retries, a failed call is not repeated. A short outage at your endpoint would then lose the call. Switch on Retry automatically when the webhook fails to repeat it:

  • Retries: The number of extra attempts after the first one, from 1 to 10. With 3 retries, Azumuta makes up to 4 calls. The default is 3.
  • Wait between retries: The time between attempts: 15 minutes, 30 minutes, 1 hour, 2 hours, 4 hours, 8 hours or 24 hours. The default is 1 hour.
  • Only retry during set hours: Tick this to limit retries to a time window, for example when your system is offline at night. Set the start and end time under Between and and, and select the Timezone. A retry that would fall outside the window waits until the window opens again. The window starts at 06:00 and ends at 22:00 by default.

Good to know:

  • Each retry sends the same event data as the first call. The retry uses the trigger as it is configured at that moment, so a new endpoint or new credentials apply to retries that are still waiting.
  • The run is recorded as Success as soon as one attempt succeeds, and as Failed once the last retry has failed.
  • If you lower the number of retries while a run is waiting, the run stops at the new limit. If you switch retries off or delete the trigger, the waiting run is recorded as failed instead of being retried.
  • The first call is made at the moment the event occurs. The window only applies to retries.

Because a retry can arrive after a call that did reach your system (for example when your system processed it but the answer got lost), design your endpoint so that receiving the same event twice does no harm. Use the X-Azumuta-Trigger-Run-Id header to recognize a repeat.

Check and retry runs

Open the trigger’s usage history to see every run. See See the list of triggers in your workspace and each trigger’s usage history.

Each run has one of these statuses:

Status Meaning
Running Azumuta is making the call.
Waiting for retry The last attempt failed and a retry is scheduled. The run shows which attempt is next (for example "Attempt 2 of 4") and when, together with the reason the last attempt failed.
Success The endpoint answered with a 2xx status.
Failed The call failed and no retries are left, or retries are switched off.

A run with more than one attempt also shows how many attempts it made.

To run the next attempt right away instead of waiting for the interval, click Retry now next to a run that is Waiting for retry.

Use the REST API to check and retry runs

An integration can read the run history and push a waiting run through itself with the Azumuta REST API. The endpoints are in the Triggers section of the in-app API docs.

Endpoint What it does
GET /api/v1/triggers/runs Lists trigger runs, newest first.
GET /api/v1/triggers/runs/{triggerRunId} Returns one run in full, including every attempt with the request it sent and the response it got back.
POST /api/v1/triggers/runs/{triggerRunId}/retry Runs the next attempt of a waiting run immediately.

List runs. Filter the list with these query parameters:

  • triggerId: only runs of these triggers.
  • status: only runs in these statuses: running, retrying (the run failed and is waiting for its next attempt), success or failed.
  • scope: only runs of triggers in these scopes.
  • productId and issueId: only runs for these product orders or issues.
  • startedAfter and startedBefore: only runs started within this time, as Unix timestamps in milliseconds.
  • limit (up to 100, default 100) and skip: page through the results.

Each run in the list has an id, triggerId, scope, type, event, status, startTime, endTime, errorMessage and, for webhooks, the endpoint and nextAttemptAt (when the next attempt is planned). To find the calls that did not get through in a period, filter on status=failed and the period.

Retrieve a run. The full run adds attempts: for every call its number, start and end time, the request (method, URL and body), the response (status and body) and, when the call could not be made at all, the error message. Credentials in the URL are redacted.

Retry a run. The run must be retrying, otherwise the call is refused. The response is the run as it stands after the attempt: success or failed if the attempt settled it, or retrying again if it failed and another attempt was scheduled. A scheduled retry that fires at the same moment does not send the request twice.

Access. Authenticate as described in Azumuta’s REST API. If the API scopes experiment is enabled for your workspace, the key needs the triggers:read scope to list runs and read them in full, and the triggers:write scope to retry a run. Reading a run in full and retrying a run also require the Manage triggers right, or the right to manage triggers of the run’s scope, for the user behind the call.

On this page