Skip to content
Archiedocscookbooknewssign in

    Events: Capture, Map, Bind

    Capture: receive an event

    Open Events → Capture. Choose New source, optionally giving it a path such as alerts.

    Copy the webhook URL and signing secret shown after creation. The secret is shown once. Configure your sender to post to that URL, which has the form:

    https://your-archie-host/webhooks/capture/alerts

    Signed sources accept an HMAC-SHA256 signature over the request's raw body in X-Hub-Signature-256 or X-Signature-256. The signature can include the sha256= prefix.

    Send an example event, then select it in Capture to inspect its payload, headers and signature status. A 202 response means archie stored the event. It doesn't mean a workflow started.

    An event without a valid signature can appear in Capture but won't dispatch. If a sender can't sign requests, use the source's unsigned approval flow. Only an approved unsigned source can dispatch unsigned events.

    If the sender retries deliveries, set the source's delivery header to the header containing its stable delivery ID. The sender must repeat that ID for retries of the same delivery so they don't start another run.

    Name the event type

    In Capture's Event types section, name the proposed group that matches your example. Review its rule so it identifies the events you want to automate. You can also create a type from a pasted payload and headers.

    The source identifies where an event arrived. Its event type identifies which kind of payload it contains. A source can receive several kinds of event, each with its own mapping and bindings.

    Events that don't match an event type aren't dispatched. Naming the type is part of setting up the automation, even when the payload is already visible in Capture.

    Map: extract the fields

    Open Map and create a mapping. Give it a name, select its event type, and choose a captured event for the preview.

    Click values in the payload to add fields. For each field, choose the name the binding will use, its type and whether it's required. Choose Preview to check the extracted values before saving.

    For example, an alert might contain:

    {
  "severity": "critical",
  "message": "Checkout errors exceed the alert threshold",
  "repository": "acme/shop"
}

    Map these values to:

    • severity, a required string used to filter alerts.
    • summary, a required string taken from message and passed to the workflow.
    • repository, a string used when the workflow needs a repository.

    A required field that's missing fails resolution. A null value or wrong type also fails. Preview against the payload your sender actually sends, especially after changing its format.

    The mapping's Source hint is a label for you. It doesn't select incoming events.

    Bind: choose what runs

    Open Bind and create a binding:

    1. Give it a name and select the event type.
    2. Choose a field mapping for that type.
    3. Add a filter if only some matching events should start work.
    4. Select the workflow.
    5. Assign its inputs from mapped parameters or constants.
    6. Choose the repository when the workflow needs one.

    For the alert example, this filter allows only high and critical severity:

    severity in ["high", "critical"]

    Filters use CEL expressions over the mapped parameter names. Here, severity is the field from Map, rather than a path into the original JSON.

    If the workflow declares a string input named summary, assign the mapped summary parameter to it. For a repository workflow, select the repository parameter or pin an owner and repository in the binding. A repository parameter must contain owner/name and name a configured repository.

    Save the binding, then choose Approve. Its status changes from pending approval to armed. Only armed bindings dispatch, and their target workflow must be enabled.

    Pause or change an automation

    Choose Pause on an armed binding to stop it dispatching. Resume returns it to pending approval, so you'll need to approve it again.

    Editing a binding also returns it to pending approval. Review the mapping, filter, workflow inputs and repository before approving the edited version.

    Find out why no run started

    Select the event in Capture and inspect Dispatches for a linked task or the reason work wasn't started. The Bind list also shows Not dispatching when the latest outcome has a failure reason.

    Check the chain in order:

    • No capture: check the webhook URL, the source's network refusals and the sender's HTTP response.
    • Captured but untrusted: check the signature or unsigned-source approval.
    • Unidentified event: create or correct its event-type rule.
    • Mapping failure: preview the capture and check required fields and types.
    • No matching work: check the filter, binding approval and whether the workflow is enabled.
    • Rejected run: check the workflow's required inputs and repository selection.

    Use a new delivery after setup to check the complete chain, then follow the task linked from Dispatches.