Help Center

Webhooks and Event Mapping

Availability: these features depend on your plan and user role. Contact your Altana account team if they're not visible in your environment.

A webhook delivers Altana events to an endpoint you control, and a mapping says which events to deliver to it. Today the event you can map is transaction screening results: when Altana finishes screening a batch of transactions, it sends the result to every webhook mapped to that event — so the outcomes flow straight into your own systems.

Setting this up is two steps: register a webhook, then map the screening event to it. This page covers both, plus the request your endpoint receives and how delivery behaves.

This is the outbound counterpart to SFTP File Ingestion, which brings transactions in to be screened. For pushing catalog product changes instead, see Catalog Subscriptions.

Set up a webhook

Register endpoints from Settings → Integrations → Webhooks.

  1. On the Webhooks tab, select Create Webhook.
  2. Enter a Name and the URL of your endpoint. The URL must use https://.
  3. Choose the HTTP Method — POST, PUT, or PATCH.
  4. Choose an Authentication Type (see Authentication for what your endpoint should check).
  5. Select the payload types the webhook accepts. A webhook only accepts events whose payload type it lists; today that is Transaction Screening Result.
  6. Optionally provide a Custom CA Certificate (PEM) if your endpoint uses a private certificate authority, and enable gzip compression if your endpoint expects it.
  7. Select Validate to confirm Altana can reach the endpoint, then Create. You can re-test, edit, or delete a webhook from the same tab.

Map an event to a webhook

A mapping connects an event to a webhook so the event is delivered automatically whenever it occurs. Create the webhook first, then map to it from Settings → Integrations → Mapping.

  1. On the Mapping tab, select Create Dispatch Mapping.
  2. Choose the Event and the Webhook to deliver it to. The webhook must support the event's payload type.
  3. Set the mapping Active (or leave it disabled to turn on later), then Create.

Available events

  • Transaction Screening Completed — delivered when a transaction screening run's results are ready.
  • All Transaction Screening Result Events — a wildcard that subscribes a webhook to every current and future screening result event, so you don't have to add new mappings as more screening event types are introduced.

Both carry the transaction screening result payload. Map either the specific event or the wildcard to a webhook — not both, since they would deliver the same result twice.

The request your endpoint receives

When screening completes, Altana sends an HTTP request (the method you configured) to each mapped webhook. The body is a JSON transaction screening result callback: the screened line items and their outcomes — screening findings, and where applicable product-classification and duty details. Fields use camelCase:

{
  "results": [
    {
      "lineItemId": "po-10481-line-3",
      /* screening findings for this line item */
      "dutyInformation": { "hsCode": "8471.30", "effectiveDutyAmount": 42.18 /* ... */ }
    }
  ],
  "errors": [
    { "lineItemId": "po-10481-line-9", "message": "..." }
  ]
}

The exact field-level schema is generated from the API and always matches your environment — read it at the /api/nexus/api-docs/ route (see API Documentation). Per-line-item errors let you reconcile which inputs screened cleanly and which need attention.

Authentication

Each webhook authenticates with the scheme you choose at registration. Your endpoint should check the corresponding header:

  • Bearer Token (JWT/JWKS) — Altana signs the request and you verify it against a public key. Optionally set a JWT audience; it defaults to your endpoint's origin.
  • Basic Auth — a username and password.
  • API Key — a key sent in a header you choose (defaults to X-API-Key).
  • OAuth2 Client Credentials — Altana fetches a token from your token URL (which must be https://) using a client ID and secret, then sends it as a bearer token.

Whichever you choose, verify it before acting on the body, and reject requests that fail the check.

Delivery and retries

  • Respond with a 2xx status to acknowledge a delivery.
  • A failed delivery — a 5xx, 429, or network error — is retried a few times with exponential backoff (about 1 to 30 seconds). A 4xx (other than 429) is treated as a permanent rejection and is not retried, so return 4xx only when the request is genuinely malformed.
  • Build your endpoint to be idempotent: a retried delivery can arrive after your endpoint already processed it.

Related