Webhook

The Webhook trigger starts a workflow when an external system POSTs to a public Splice URL. It is the primary way to integrate Splice with carrier APIs, TMS callbacks, customer portals, and any other system that pushes data over HTTP. The same node also serves as the AS2 receiver when configured for the AS2 protocol.

Overview

Use the Webhook trigger when you need to:

• React to real-time events - Carrier delivery notifications, TMS shipment updates, third-party system alerts
• Accept inbound EDI over AS2 - Receive signed and encrypted EDI from trading partners with full MDN handling
• Receive file uploads - Accept multipart form posts and stage attachments in workflow storage
• Expose a public callback URL - Give partners a stable endpoint to push data into a workflow
• Authenticate inbound calls - Verify caller identity with Basic auth, custom headers, RSA signatures, or AS2 certificate trust

Endpoint URL

Each webhook-triggered workflow exposes a public HTTPS endpoint of the form:

POST https://<your-splice-api-domain>/hook/{workflowId}
POST https://<your-splice-api-domain>/hook/{workflowId}/{proxy+}

• {workflowId} - The ID of the workflow whose webhook trigger should fire.
• {proxy+} - (Optional) Any additional path suffix is forwarded to the workflow as the path parameter. Useful for partners that vary their callback path per event type.

The endpoint accepts only POST. Sending GET, PUT, etc. returns a 4xx from API Gateway. Inactive or non-existent workflows return an empty 200 — this is intentional, since the URL is public and probing should not reveal workflow state.

Configuration

Authentication

Selects how callers prove their identity. Each option binds to a credential that supplies the secret material.

Option	Credential	Behavior
None (default)	—	No authentication. The workflow runs whenever the URL is hit. Use only for callers that cannot supply credentials and where the workflow is idempotent.
Basic Auth	HTTP Basic Auth credential (user, password)	Caller must include Authorization: Basic <base64(user:password)>. Mismatched credentials return 403.
Header Auth	HTTP Header Auth credential (name, value)	Caller must include the configured header with the configured value. Header name is matched case-insensitively.
AS2 Receiver Auth	AS2 Receiver credential (receiver cert, optional partner signer cert)	Required when Protocol is AS2. The decrypted/verified payload becomes the workflow input and the node returns a signed MDN.

RSA Signature Auth

The handler also supports RSA signature verification for advanced integrations: the caller signs the request body with a private key and sends the base64 signature in a configured header; Splice verifies it with the stored public key (SHA-256 / SPKI / PEM). This option is not exposed in the standard authentication dropdown — contact support if you need it provisioned for a specific partner.

HTTP Method

Currently fixed to POST. The webhook only listens for POST requests.

Protocol

Option	Behavior
HTTP (default)	Standard HTTP webhook. Body is parsed by content type (see below).
AS2	AS2 receiver mode. The body is treated as a PKCS#7 encrypted/signed AS2 message, decrypted with the receiver credential, and an MDN is returned to the partner. Authentication MUST be set to AS2 Receiver Auth — any other value returns 401.

Expected AS2-From (AS2 only)

Optional. When set, inbound AS2 messages whose AS2-From header does not match this exact value are rejected with an authentication-failed MDN. Use this to scope a workflow to one specific partner identity even when the linked AS2 receiver credential could authenticate multiple senders.

Expected AS2-To (AS2 only)

Optional. When set, inbound AS2 messages whose AS2-To header does not match this value are rejected with an authentication-failed MDN. Useful when a single Splice tenant serves multiple AS2 identities and each workflow handles only one.

Options

Ignore Bots

When enabled, requests from known bot user-agents (link previewers, web crawlers) are rejected with 403 before reaching the workflow. Bot detection uses the User-Agent header; recommended for any webhook URL that may be linked from email, chat, or social media.

Raw Body

When enabled, the entire request body is written to workflow temporary storage as a file rather than parsed. Downstream nodes receive a { file: <storagePath> } reference instead of a parsed object. Use this when:

• The payload is binary (PDF, ZIP, Excel) and parsing it as JSON would corrupt it.
• The downstream workflow needs the bytes-as-received for signature verification or archival.
• The payload is too large to keep in memory through the queue.

For AS2 protocol, payloads are always written to storage — the Raw Body option does not need to be set.

No Response Body

When enabled, the webhook returns an empty 200 body. Some callers reject responses with bodies; others log them. Defaults to off.

Response Data

A custom response body to return when the webhook successfully enqueues the workflow. Supports template expressions. Useful when a partner expects a specific acknowledgement payload (e.g., "ACK", a SOAP envelope, a JSON receipt). When unset, the webhook returns an empty {}.

Response Headers

Add custom response headers as name / value pairs. Use cases include partner-required X-Correlation-Id echo headers, custom Content-Type overrides, or compatibility headers for legacy clients.

Binary Data / Binary Property (HTTP only)

Legacy options retained for compatibility with older workflows that handled binary uploads via a named binary property. New workflows should prefer Raw Body or rely on the multipart form-data handling described below.

Body Parsing

For HTTP protocol, the request body is parsed based on the Content-Type header:

Content-Type	Workflow input shape
application/json (default fallback)	JSON.parse(body) — the JSON object becomes the workflow input
application/x-www-form-urlencoded	Parsed query-string object: { field: "value", ... }
multipart/form-data	Each text field becomes a property; each uploaded file is stored and replaced with its storage path: { field: "value", upload: "<storagePath>" }
text/xml	Raw XML string
text/plain	{ text: "<body>" }
application/pkcs7-mime (AS2 only)	Decrypted, signature-verified, and stored as a file. Workflow receives { file, as2: { from, to, messageId, ... } }

If Raw Body is enabled, parsing is skipped and the full body is written to storage instead.

Output

The webhook trigger emits a single output keyed by the trigger node's name. Downstream nodes reference the parsed payload through that key.

HTTP example

A POST /hook/{id} with a JSON body and a node named Webhook produces:

{
  "Webhook": {
    "shipmentId": "S-12345",
    "status": "delivered"
  }
}

AS2 example

A successful AS2 receipt produces:

{
  "Webhook": {
    "file": "trigger/<resourceId>/<timestamp>/invoice.edi",
    "as2": {
      "from": "PARTNER-PROD",
      "to": "ACME-PROD",
      "messageId": "<abc123@partner.example>",
      "receivedAt": "2026-04-28T17:32:11.000Z",
      "contentType": "application/EDI-X12",
      "subject": "EDI 850 Drop",
      "filename": "invoice.edi"
    }
  }
}

For multi-attachment AS2 messages (multipart/mixed with EDIINT-Features: multiple-attachments), each attachment triggers a separate workflow execution. Each execution carries as2.batchIndex and as2.batchSize so downstream logic can correlate attachments back to the original AS2 message. Only one MDN is returned to the partner regardless of attachment count.

Example Usage & Common Use Cases

Carrier Delivery Notification

A carrier POSTs JSON to a Splice URL when a shipment is delivered:

Authentication: Header Auth
Header Auth Credential: Carrier API Key
Protocol: HTTP

[Webhook] → [Set: extract POD fields] → [HTTP Request: update TMS] → [Send Email: notify customer]

Inbound EDI Over AS2

Receive a signed/encrypted X12 850 from a retail partner and route into the EDI ingestion pipeline:

Authentication: AS2 Receiver Auth
AS2 Receiver Auth Credential: BigRetailer Receiver
Protocol: AS2
Expected AS2-From: BIGRETAILER-PROD
Expected AS2-To: ACME-PROD

[Webhook] → [EDI: Read 850] → [Validate] → [Store in WMS]

File Upload from a Customer Portal

Customer portal POSTs a multipart form with a CSV upload:

Authentication: Basic Auth
Basic Auth Credential: Portal Service Account
Protocol: HTTP

[Webhook] → [Spreadsheet: parse CSV] → [Loop: rows] → [Create Order]

Custom Acknowledgement Response

Return a partner-specific acknowledgement string after the workflow is enqueued:

Options:
  Response Data: ACK-{{$json.referenceNumber}}
  Response Headers: Content-Type = text/plain

[Webhook] → [enqueue downstream processing]

Path-Based Routing

A partner uses one base URL with different path suffixes per event type:

POST /hook/<workflowId>/order/created
POST /hook/<workflowId>/order/cancelled

Splice forwards the suffix as path on the workflow input, allowing a single workflow to branch on event type:

[Webhook] → [If: path contains "cancelled"] → [Cancel Order] / [Create Order]

How It Works

1. Resolve workflow - The path's {id} is looked up in the workflow repository. Missing or inactive workflows return an empty 200 (silent on a public endpoint).
2. Identify the trigger node - The first non-error trigger node in the workflow graph is selected. Its parameters drive auth, protocol, and option behavior.
3. Authenticate - The configured authentication strategy runs against the request headers. Failures return 401 (missing) or 403 (mismatched).
4. Validate AS2 envelope (AS2 only) - Message-Id, AS2-From, and AS2-To headers are required; missing headers return a 400 with a failure MDN. Pinned Expected AS2-From / Expected AS2-To are checked next.
5. Parse / decrypt the body - HTTP bodies are parsed per content type; AS2 bodies are decrypted with the receiver private key, signature-verified, and (optionally) signer-fingerprint matched against the configured partner cert.
6. Stage payloads - For multipart, raw-body, and AS2 flows, payloads are written to S3 under a per-execution trigger/<resourceId>/<timestamp>/<filename> prefix. AS2 partner-supplied filenames are sanitized (path components and control chars stripped) before storage.
7. Enqueue execution - A workflow execution message is published to either the default execution queue or a node-type-specific trigger queue. AS2 multi-attachment messages enqueue one execution per attachment.
8. Respond to caller - For HTTP, returns the configured response data (or empty 200). For AS2, returns a signed MDN whose disposition reflects the verification and queue-send result.

AS2 Receiver Behavior

When Protocol is AS2, the webhook implements an AS2 receiver per RFC 4130:

• Decryption - The PKCS#7 enveloped-data is decrypted with the receiver private key from the AS2 Receiver credential.
• Signature verification - The inner signed body is verified. When a Partner Signer Certificate is configured on the credential, the inbound signer cert is fingerprint-matched and authentication-failed is returned on mismatch. Without a configured partner signer, verification falls back to signature math alone — secure but not partner-pinned.
• MDN generation - A signed (or unsigned, per partner request) MDN is returned with the correct Received-Content-MIC, AS2-From / AS2-To swapped relative to the request, and a processed or failure disposition.
• Failure MDNs - Any verification, decryption, or downstream queue-send failure produces a failure MDN with a specific failureReason (authentication-failed, decryption-failed, unexpected-processing-error, etc.) so the partner can retry or escalate.
• Queue-send safety - If decryption succeeds but enqueueing the workflow execution fails, the partner receives a failure MDN rather than a misleading 200. This protects against silent data loss when the partner would otherwise believe the message was accepted.

Best Practices

Authentication

• Always authenticate webhooks reachable from the public internet - The URL itself is not a secret. Use Basic Auth or Header Auth at minimum; AS2 Receiver Auth provides certificate-grade trust for B2B use.
• Pin AS2 partner identity - Set Expected AS2-From / Expected AS2-To so a workflow only accepts messages from one specific partner identity, even if the underlying credential trusts more.
• Treat header auth tokens as passwords - Rotate them on partner offboarding or any suspected compromise.

Body Handling

• Use Raw Body for binary or large payloads - Parsing 10 MB JSON in-memory is wasteful and fragile; staging to S3 is cheap and lets downstream nodes stream.
• Match the partner's content type - If the partner sends text/xml, do not configure the workflow for JSON; the body parser dispatches on the Content-Type header, not on workflow expectation.

Response Handling

• Set Response Data when the partner requires a specific ack - Many partners reject the workflow if the response body isn't shaped how they expect. Some require XML SOAP envelopes; others want a specific JSON shape.
• Keep responses fast - The webhook returns as soon as the workflow execution is enqueued, not when it completes. Long-running logic belongs in downstream nodes, not in any synchronous response shaping.

Reliability

• Plan for retries - Most partners retry on non-2xx responses. The webhook is idempotent at the queue layer (each retry produces a new execution); downstream nodes should be idempotent on the partner's message ID where possible.
• Monitor failure rates - Authentication failures (403) often indicate partner credential drift; queue-send failures (5xx / failure MDN) indicate Splice-side incidents.

Troubleshooting

Common Issues

• Webhook returns 200 but no workflow runs - The workflow is inactive, doesn't exist, or has no trigger node. Public-facing 200s are intentional; confirm the workflow is active and has a webhook trigger configured.
• 403 Authorization data is wrong - The supplied auth credentials don't match the credential record. For Basic Auth, check the user / password on the credential. For Header Auth, check the header name (case-insensitive) and value.
• 401 Authorization is required - The expected auth header is missing entirely, or the workflow expects AS2 auth but the protocol/auth combination is wrong.
• AS2 partner sees "MDN pending" - Almost always a Received-Content-MIC mismatch. Confirm the partner's MIC algorithm matches the receiver's, and that there is no body transformation (e.g., a proxy stripping CRLFs) between the partner and Splice.
• Multipart upload arrives as a JSON-parse error - The partner is sending multipart/form-data with a malformed boundary, or sending raw binary with a missing Content-Type. Check CloudWatch for the request headers.
• Bot-noise floods the workflow - Enable Ignore Bots in options to filter requests with crawler user-agents.

Debugging Tips

• Inspect CloudWatch logs - The webhook logs the full event at INFO level on entry. AS2 emits structured events (as2.decrypt-start, as2.verify-success, as2.queue-send-success, etc.) keyed by workflow ID and message ID.
• Verify the URL - Copy the public URL from the workflow's webhook node; the path includes the workflow ID exactly as it must appear in callers.
• Test with curl before pointing partners at it - A simple curl -X POST -H 'Content-Type: application/json' -d '{...}' https://<api>/hook/<id> confirms the URL, auth, and body shape end-to-end before the partner is involved.
• Check sample data - The webhook captures the parsed payload as node sample data on each successful enqueue, accessible from the workflow editor for downstream node design.

Related

• AS2 Node - Send signed and encrypted AS2 messages to trading partners (the outbound counterpart to AS2 webhook receipt)
• Trigger Nodes - Overview of all available workflow trigger types