Webhooks

Webhook Setup

Configure a webhook URL in Settings → Webhooks to receive lane-matched document lifecycle updates without polling. Create separate Certification and Production endpoints. Lab uses a signed one-shot probe and never creates a persistent delivery.

SignalEDI sends a POST request to your URL with the following JSON payload:

{
  "id": "evt_01HXYZ",
  "type": "document.accepted.v1",
  "version": "1",
  "createdAt": "2026-09-24T14:00:00.000Z",
  "documentId": "doc_out_01HXYZ",
  "direction": "CUSTOMER_TO_PARTNER",
  "environment": "CERTIFICATION",
  "partnerId": "partner_demo",
  "standard": "x12",
  "documentTypeCodes": ["850"],
  "status": "ACCEPTED",
  "links": {
    "self": "/v1/documents/doc_out_01HXYZ",
    "payload": "/v1/documents/doc_out_01HXYZ/payload"
  }
}

Versioned events include document.accepted.v1, document.available.v1, document.transport_delivered.v1, document.delivery_failed.v1, document.acknowledgement_received.v1, and document.held.v1. Default events contain metadata and authorized pull links, not document contents. Deliveries include X-SignalEDI-Timestamp, X-SignalEDI-Event, and X-SignalEDI-Delivery-ID headers. document.acknowledgement_received.v1 fires for a partner 997, 999, or EDIFACT CONTRL linked to a document admitted through the v1 API; TA1 and 277 responses do not produce a webhook.

Legacy events are still emitted and subscribable; they are signed over the raw body only and carry no timestamp header: transaction.completed, transaction.failed, document.partner_ack, document.ack_overdue, file.processed, mapping.draft.ready, onboarding.certification.requested, onboarding.certified, onboarding.live, incident.opened, incident.resolved, pa.sla.escalation, pa.sla.breach, compliance.risk.detected, compliance.check.resolved.

Verify webhook authenticity by checking the X-SignalEDI-Signature header (HMAC-SHA256 over timestamp + "." + rawBody using your webhook signing secret; reject deliveries whose timestamp skew exceeds ~5 minutes). Deduplicate on X-SignalEDI-Delivery-ID and confirm the environment header matches the endpoint lane.