Webhooks & Endpoints

Endpoints define how x12port exchanges EDI documents with your trading partners. Manage them at /endpoints.

What is an Endpoint?

An endpoint is the communication channel between you and one trading partner. It tells x12port where to send outbound documents and how to receive inbound ones. One trading partner can have multiple endpoints (e.g. AS2 for production, SFTP for testing).

Endpoint Types

Type	Best for	Key requirements
AS2	Large retailers (Walmart, Target, Amazon, Home Depot, Kroger). Required by most major retail trading partners.	AS2 ID for both sides, partner URL, SSL certificates, MDN acknowledgment settings
SFTP	Mid-market partners, 3PLs, manufacturers. Simpler to set up than AS2.	Host, port, username, SSH key or password, inbox path, outbox path
API	Modern ERP, WMS, or OMS integrations that expose a REST endpoint.	Endpoint URL, auth type (API key, Bearer token, Basic auth), HTTP method
VAN	Value-Added Networks — SPS Commerce, TrueCommerce, GS1, 1 EDI Source.	VAN provider name, mailbox ID, credentials provided by the VAN

Creating an Endpoint

Go to /endpoints
Click + New Endpoint
Select the endpoint type (AS2, SFTP, API, or VAN)
Select the trading partner this endpoint connects to
Fill in the type-specific fields (see below)
Click Save Endpoint

AS2 Fields

Field	Description
My AS2 ID	Your AS2 identifier — provided to you by your trading partner during onboarding
Partner AS2 ID	Your partner's AS2 identifier — from their EDI implementation guide
Partner URL	The HTTPS URL where you send outbound documents (their AS2 server)
Signing Certificate	Your partner's public certificate for verifying signed messages
Encryption Certificate	Your partner's public certificate for encrypting outbound payloads
MDN Type	Synchronous (response in same HTTP session) or Asynchronous (MDN sent to a separate URL)

SFTP Fields

Field	Description
Host	SFTP server hostname or IP
Port	Default 22; some partners use a non-standard port
Username	SFTP login username
Auth Method	SSH Key (preferred) or Password
Inbox Path	Remote directory where your partner drops inbound documents for you
Outbox Path	Remote directory where x12port deposits outbound documents for your partner to pick up

Webhooks

Webhooks let x12port notify your system when EDI events happen — a document arrives, a 997 is received, or a transmission fails. Configure a webhook URL on any endpoint to receive HTTP POST notifications.

Each webhook payload is a JSON object containing:

event — the event type (e.g. document.received, ack.sent, transmission.failed)
partner — the trading partner name and ISA ID
transaction_set — the X12 document type (e.g. 850)
document_id — the vault ID of the document (use the API to retrieve the content)
timestamp — ISO 8601 UTC timestamp

ℹ️ Use webhook events to trigger downstream processing — for example, when an 856 ASN arrives, fire a webhook that tells your WMS to expect the inbound shipment.

Endpoint Status

Each endpoint on the /endpoints page shows a status badge:

Status	Meaning
Active	Connected and processing normally
Pending	Created but not yet tested or confirmed by trading partner
Error	Last transmission failed — check the endpoint detail for the error log
Inactive	Manually disabled — no documents will be sent or received

Testing an Endpoint

After creating an endpoint, use the Send Test button to transmit a minimal valid X12 document (a 997 functional acknowledgment by default) to the partner. If the test succeeds, the endpoint status changes to Active. For SFTP, the test writes a small probe file to the outbox path and then deletes it.