{ "openapi": "3.1.0", "info": { "title": "Ecourier Webhooks", "version": "1.0.0", "description": "Outbound webhook events POSTed to URLs you configure.\n\nVerify the authenticity of the request by checking the Signature header using HMAC-SHA256 over the raw JSON body and your webhook secret.\n\nWebhooks can be managed in the Ecourier dashboard." }, "servers": [ { "url": "https://api.ecourier.io/v1" } ], "tags": [ { "name": "Events", "description": "Ecourier sends these JSON payloads as HTTP POST requests to webhook URLs you configure." } ], "components": { "schemas": { "WebhookDocumentParticipant": { "type": "object", "properties": { "participant_identifier_scheme": { "type": "string", "description": "Participant identifier scheme code (for example GLN, DK:CVR).", "example": "GLN" }, "participant_identifier_icd": { "type": "string", "description": "ICD code for the scheme, used in Peppol-style actor identifiers.", "example": "0088" }, "participant_id": { "type": "string", "description": "Participant id in the given scheme (without scheme prefix).", "example": "5790000435944" }, "participant_identifier": { "type": "string", "description": "Canonical participant identifier in `scheme:id` form used for routing and display.", "example": "0088:5790000435944" } }, "required": [ "participant_identifier_scheme", "participant_identifier_icd", "participant_id", "participant_identifier" ], "title": "WebhookDocumentParticipant" }, "WebhookDocumentPayload": { "type": "object", "properties": { "id": { "type": "string", "description": "Ecourier document identifier (ULID).", "example": "01arz3ndektsv4rrffq69g2f1w" }, "dashboard_url": { "type": "string", "description": "URL to open this document in the Ecourier dashboard.", "example": "https://app.ecourier.io/test/acme-corp/documents/01arz3ndektsv4rrffq69g2f1w" }, "created_at": { "type": [ "string", "null" ], "description": "ISO 8601 timestamp when the document was created, if known.", "example": "2026-04-11T10:00:00+00:00" }, "delivered_at": { "type": [ "string", "null" ], "description": "ISO 8601 timestamp when the document reached a delivered state, if applicable.", "example": "2026-04-11T11:30:00+00:00" }, "channel": { "type": "string", "description": "Transport channel for the document (for example Peppol).", "example": "Peppol" }, "e2e_message_uuid": { "type": [ "string", "null" ], "description": "End-to-end message UUID for the business message, when available.", "example": "550e8400-e29b-41d4-a716-446655440006" }, "e2e_transmission_id": { "type": [ "string", "null" ], "description": "Transmission identifier from the latest document send attempt, when available.", "example": "transmission-id@peppol.ap.ecourier.io" }, "sender": { "description": "Sending party (participant) as routed on the network.", "example": { "participant_identifier_scheme": "GLN", "participant_identifier_icd": "0088", "participant_id": "5790000435944", "participant_identifier": "0088:5790000435944" }, "$ref": "#/components/schemas/WebhookDocumentParticipant" }, "receiver": { "description": "Receiving party (participant) as routed on the network.", "example": { "participant_identifier_scheme": "GLN", "participant_identifier_icd": "0088", "participant_id": "5798000987654", "participant_identifier": "0088:5798000987654" }, "$ref": "#/components/schemas/WebhookDocumentParticipant" }, "status": { "type": "string", "description": "Document lifecycle status at dispatch time (string enum value).", "example": "Delivered" }, "type": { "type": "string", "description": "Document type at dispatch time (string enum value), for example Invoice or CreditNote.", "example": "Invoice" }, "ubl": { "description": "UBL identifiers and profile metadata extracted from the document, when present.", "example": { "id": "INV-400", "uuid": "660e8400-e29b-41d4-a716-446655440007", "profile_id": "urn:fdc:peppol.eu:2017:poacc:billing:01:1.0", "customization_id": "urn:cen.eu:en16931:2017" }, "$ref": "#/components/schemas/WebhookDocumentUbl" } }, "required": [ "id", "dashboard_url", "channel", "sender", "receiver", "status", "type", "ubl" ], "title": "WebhookDocumentPayload" }, "WebhookDocumentUbl": { "type": "object", "properties": { "id": { "type": [ "string", "null" ], "description": "UBL document identifier (often the business document number), when extracted.", "example": "INV-400" }, "uuid": { "type": [ "string", "null" ], "description": "UBL UUID for the document instance, when extracted.", "example": "660e8400-e29b-41d4-a716-446655440007" }, "profile_id": { "type": [ "string", "null" ], "description": "UBL ProfileID value when extracted from the document.", "example": "urn:fdc:peppol.eu:2017:poacc:billing:01:1.0" }, "customization_id": { "type": [ "string", "null" ], "description": "UBL CustomizationID value when extracted from the document.", "example": "urn:cen.eu:en16931:2017" } }, "title": "WebhookDocumentUbl" }, "WebhookEnvelopeDocumentReceiveCreated": { "type": "object", "properties": { "event_id": { "type": "string", "description": "Unique identifier for the webhook event. Can be used for deduplication.", "example": "01hz8q3v7n8w9x0y1z2a3b4c5d" }, "event": { "type": "string", "description": "Event type for this delivery. In each webhook-specific schema this is a fixed literal (the value shown in the docs).", "example": "Document.Receive.Created", "const": "Document.Receive.Created" }, "occurred_at": { "type": "string", "description": "ISO 8601 timestamp of when the event was recorded (same moment as the webhook dispatch).", "example": "2026-04-11T12:34:56+00:00" }, "version": { "type": "integer", "description": "Version of the webhook event schema.", "example": 1 }, "team_id": { "type": "string", "description": "The ID of the team that the webhook event belongs to.", "example": "01hqabcdef1234567890abcd" }, "mode": { "type": "string", "description": "The mode where the webhook event was triggered.", "enum": [ "Live", "Test" ], "example": "Live" }, "company_id": { "type": [ "string", "null" ], "description": "The ID of the company that the webhook event belongs to.", "example": "01knwp7zdfpmw1v9hc4g7pj7zz" }, "payload": { "description": "Event-specific payload.", "$ref": "#/components/schemas/WebhookInnerPayload" } }, "required": [ "event_id", "event", "occurred_at", "version", "team_id", "mode", "payload" ], "title": "WebhookEnvelopeDocumentReceiveCreated" }, "WebhookEnvelopeDocumentReceiveDelivered": { "type": "object", "properties": { "event_id": { "type": "string", "description": "Unique identifier for the webhook event. Can be used for deduplication.", "example": "01hz8q3v7n8w9x0y1z2a3b4c5d" }, "event": { "type": "string", "description": "Event type for this delivery. In each webhook-specific schema this is a fixed literal (the value shown in the docs).", "example": "Document.Receive.Delivered", "const": "Document.Receive.Delivered" }, "occurred_at": { "type": "string", "description": "ISO 8601 timestamp of when the event was recorded (same moment as the webhook dispatch).", "example": "2026-04-11T12:34:56+00:00" }, "version": { "type": "integer", "description": "Version of the webhook event schema.", "example": 1 }, "team_id": { "type": "string", "description": "The ID of the team that the webhook event belongs to.", "example": "01hqabcdef1234567890abcd" }, "mode": { "type": "string", "description": "The mode where the webhook event was triggered.", "enum": [ "Live", "Test" ], "example": "Live" }, "company_id": { "type": [ "string", "null" ], "description": "The ID of the company that the webhook event belongs to.", "example": "01knwp7zdfpmw1v9hc4g7pj7zz" }, "payload": { "description": "Event-specific payload.", "$ref": "#/components/schemas/WebhookInnerPayload" } }, "required": [ "event_id", "event", "occurred_at", "version", "team_id", "mode", "payload" ], "title": "WebhookEnvelopeDocumentReceiveDelivered" }, "WebhookEnvelopeDocumentReceiveReady": { "type": "object", "properties": { "event_id": { "type": "string", "description": "Unique identifier for the webhook event. Can be used for deduplication.", "example": "01hz8q3v7n8w9x0y1z2a3b4c5d" }, "event": { "type": "string", "description": "Event type for this delivery. In each webhook-specific schema this is a fixed literal (the value shown in the docs).", "example": "Document.Receive.Ready", "const": "Document.Receive.Ready" }, "occurred_at": { "type": "string", "description": "ISO 8601 timestamp of when the event was recorded (same moment as the webhook dispatch).", "example": "2026-04-11T12:34:56+00:00" }, "version": { "type": "integer", "description": "Version of the webhook event schema.", "example": 1 }, "team_id": { "type": "string", "description": "The ID of the team that the webhook event belongs to.", "example": "01hqabcdef1234567890abcd" }, "mode": { "type": "string", "description": "The mode where the webhook event was triggered.", "enum": [ "Live", "Test" ], "example": "Live" }, "company_id": { "type": [ "string", "null" ], "description": "The ID of the company that the webhook event belongs to.", "example": "01knwp7zdfpmw1v9hc4g7pj7zz" }, "payload": { "description": "Event-specific payload.", "$ref": "#/components/schemas/WebhookInnerPayload" } }, "required": [ "event_id", "event", "occurred_at", "version", "team_id", "mode", "payload" ], "title": "WebhookEnvelopeDocumentReceiveReady" }, "WebhookEnvelopeDocumentSendCreated": { "type": "object", "properties": { "event_id": { "type": "string", "description": "Unique identifier for the webhook event. Can be used for deduplication.", "example": "01hz8q3v7n8w9x0y1z2a3b4c5d" }, "event": { "type": "string", "description": "Event type for this delivery. In each webhook-specific schema this is a fixed literal (the value shown in the docs).", "example": "Document.Send.Created", "const": "Document.Send.Created" }, "occurred_at": { "type": "string", "description": "ISO 8601 timestamp of when the event was recorded (same moment as the webhook dispatch).", "example": "2026-04-11T12:34:56+00:00" }, "version": { "type": "integer", "description": "Version of the webhook event schema.", "example": 1 }, "team_id": { "type": "string", "description": "The ID of the team that the webhook event belongs to.", "example": "01hqabcdef1234567890abcd" }, "mode": { "type": "string", "description": "The mode where the webhook event was triggered.", "enum": [ "Live", "Test" ], "example": "Live" }, "company_id": { "type": [ "string", "null" ], "description": "The ID of the company that the webhook event belongs to.", "example": "01knwp7zdfpmw1v9hc4g7pj7zz" }, "payload": { "description": "Event-specific payload.", "$ref": "#/components/schemas/WebhookInnerPayload" } }, "required": [ "event_id", "event", "occurred_at", "version", "team_id", "mode", "payload" ], "title": "WebhookEnvelopeDocumentSendCreated" }, "WebhookEnvelopeDocumentSendDelivered": { "type": "object", "properties": { "event_id": { "type": "string", "description": "Unique identifier for the webhook event. Can be used for deduplication.", "example": "01hz8q3v7n8w9x0y1z2a3b4c5d" }, "event": { "type": "string", "description": "Event type for this delivery. In each webhook-specific schema this is a fixed literal (the value shown in the docs).", "example": "Document.Send.Delivered", "const": "Document.Send.Delivered" }, "occurred_at": { "type": "string", "description": "ISO 8601 timestamp of when the event was recorded (same moment as the webhook dispatch).", "example": "2026-04-11T12:34:56+00:00" }, "version": { "type": "integer", "description": "Version of the webhook event schema.", "example": 1 }, "team_id": { "type": "string", "description": "The ID of the team that the webhook event belongs to.", "example": "01hqabcdef1234567890abcd" }, "mode": { "type": "string", "description": "The mode where the webhook event was triggered.", "enum": [ "Live", "Test" ], "example": "Live" }, "company_id": { "type": [ "string", "null" ], "description": "The ID of the company that the webhook event belongs to.", "example": "01knwp7zdfpmw1v9hc4g7pj7zz" }, "payload": { "description": "Event-specific payload.", "$ref": "#/components/schemas/WebhookInnerPayload" } }, "required": [ "event_id", "event", "occurred_at", "version", "team_id", "mode", "payload" ], "title": "WebhookEnvelopeDocumentSendDelivered" }, "WebhookEnvelopeDocumentSendFailed": { "type": "object", "properties": { "event_id": { "type": "string", "description": "Unique identifier for the webhook event. Can be used for deduplication.", "example": "01hz8q3v7n8w9x0y1z2a3b4c5d" }, "event": { "type": "string", "description": "Event type for this delivery. In each webhook-specific schema this is a fixed literal (the value shown in the docs).", "example": "Document.Send.Failed", "const": "Document.Send.Failed" }, "occurred_at": { "type": "string", "description": "ISO 8601 timestamp of when the event was recorded (same moment as the webhook dispatch).", "example": "2026-04-11T12:34:56+00:00" }, "version": { "type": "integer", "description": "Version of the webhook event schema.", "example": 1 }, "team_id": { "type": "string", "description": "The ID of the team that the webhook event belongs to.", "example": "01hqabcdef1234567890abcd" }, "mode": { "type": "string", "description": "The mode where the webhook event was triggered.", "enum": [ "Live", "Test" ], "example": "Live" }, "company_id": { "type": [ "string", "null" ], "description": "The ID of the company that the webhook event belongs to.", "example": "01knwp7zdfpmw1v9hc4g7pj7zz" }, "payload": { "description": "Event-specific payload.", "$ref": "#/components/schemas/WebhookInnerPayload" } }, "required": [ "event_id", "event", "occurred_at", "version", "team_id", "mode", "payload" ], "title": "WebhookEnvelopeDocumentSendFailed" }, "WebhookInnerPayload": { "type": "object", "properties": { "document": { "description": "Snapshot of the document this webhook refers to, including participants and UBL metadata.", "$ref": "#/components/schemas/WebhookDocumentPayload" } }, "required": [ "document" ], "title": "WebhookInnerPayload" } } }, "paths": {}, "webhooks": { "document_send_created": { "post": { "operationId": "documentSendCreated", "tags": [ "Events" ], "summary": "Document.Send.Created", "description": "Document created for sending\n\nThe `event` field in the JSON body is `Document.Send.Created`.\n\nSent as a POST request to the URL configured in your webhook settings.", "security": [ {} ], "parameters": [ { "name": "Signature", "in": "header", "required": true, "description": "HMAC-SHA256 hex digest of the raw JSON request body, using your webhook secret as the key.", "schema": { "type": "string" }, "example": "38b3a292d88f8eca9c6fe9bb7bb17bb3104c56e6e171e917711585e577fefd42" }, { "name": "Timestamp", "in": "header", "required": true, "description": "The UNIX timestamp of the request, in seconds.", "schema": { "type": "string" }, "example": 1681234567 } ], "requestBody": { "required": true, "description": "JSON body delivered to your webhook URL.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEnvelopeDocumentSendCreated" } } } }, "responses": { "200": { "description": "Your endpoint should return 2xx to acknowledge receipt." } } } }, "document_send_delivered": { "post": { "operationId": "documentSendDelivered", "tags": [ "Events" ], "summary": "Document.Send.Delivered", "description": "Document successfully delivered\n\nThe `event` field in the JSON body is `Document.Send.Delivered`.\n\nSent as a POST request to the URL configured in your webhook settings.", "security": [ {} ], "parameters": [ { "name": "Signature", "in": "header", "required": true, "description": "HMAC-SHA256 hex digest of the raw JSON request body, using your webhook secret as the key.", "schema": { "type": "string" }, "example": "38b3a292d88f8eca9c6fe9bb7bb17bb3104c56e6e171e917711585e577fefd42" }, { "name": "Timestamp", "in": "header", "required": true, "description": "The UNIX timestamp of the request, in seconds.", "schema": { "type": "string" }, "example": 1681234567 } ], "requestBody": { "required": true, "description": "JSON body delivered to your webhook URL.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEnvelopeDocumentSendDelivered" } } } }, "responses": { "200": { "description": "Your endpoint should return 2xx to acknowledge receipt." } } } }, "document_send_failed": { "post": { "operationId": "documentSendFailed", "tags": [ "Events" ], "summary": "Document.Send.Failed", "description": "Document failed to deliver\n\nThe `event` field in the JSON body is `Document.Send.Failed`.\n\nSent as a POST request to the URL configured in your webhook settings.", "security": [ {} ], "parameters": [ { "name": "Signature", "in": "header", "required": true, "description": "HMAC-SHA256 hex digest of the raw JSON request body, using your webhook secret as the key.", "schema": { "type": "string" }, "example": "38b3a292d88f8eca9c6fe9bb7bb17bb3104c56e6e171e917711585e577fefd42" }, { "name": "Timestamp", "in": "header", "required": true, "description": "The UNIX timestamp of the request, in seconds.", "schema": { "type": "string" }, "example": 1681234567 } ], "requestBody": { "required": true, "description": "JSON body delivered to your webhook URL.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEnvelopeDocumentSendFailed" } } } }, "responses": { "200": { "description": "Your endpoint should return 2xx to acknowledge receipt." } } } }, "document_receive_created": { "post": { "operationId": "documentReceiveCreated", "tags": [ "Events" ], "summary": "Document.Receive.Created", "description": "Document received\n\nThe `event` field in the JSON body is `Document.Receive.Created`.\n\nSent as a POST request to the URL configured in your webhook settings.", "security": [ {} ], "parameters": [ { "name": "Signature", "in": "header", "required": true, "description": "HMAC-SHA256 hex digest of the raw JSON request body, using your webhook secret as the key.", "schema": { "type": "string" }, "example": "38b3a292d88f8eca9c6fe9bb7bb17bb3104c56e6e171e917711585e577fefd42" }, { "name": "Timestamp", "in": "header", "required": true, "description": "The UNIX timestamp of the request, in seconds.", "schema": { "type": "string" }, "example": 1681234567 } ], "requestBody": { "required": true, "description": "JSON body delivered to your webhook URL.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEnvelopeDocumentReceiveCreated" } } } }, "responses": { "200": { "description": "Your endpoint should return 2xx to acknowledge receipt." } } } }, "document_receive_ready": { "post": { "operationId": "documentReceiveReady", "tags": [ "Events" ], "summary": "Document.Receive.Ready", "description": "Document ready for processing\n\nThe `event` field in the JSON body is `Document.Receive.Ready`.\n\nSent as a POST request to the URL configured in your webhook settings.", "security": [ {} ], "parameters": [ { "name": "Signature", "in": "header", "required": true, "description": "HMAC-SHA256 hex digest of the raw JSON request body, using your webhook secret as the key.", "schema": { "type": "string" }, "example": "38b3a292d88f8eca9c6fe9bb7bb17bb3104c56e6e171e917711585e577fefd42" }, { "name": "Timestamp", "in": "header", "required": true, "description": "The UNIX timestamp of the request, in seconds.", "schema": { "type": "string" }, "example": 1681234567 } ], "requestBody": { "required": true, "description": "JSON body delivered to your webhook URL.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEnvelopeDocumentReceiveReady" } } } }, "responses": { "200": { "description": "Your endpoint should return 2xx to acknowledge receipt." } } } }, "document_receive_delivered": { "post": { "operationId": "documentReceiveDelivered", "tags": [ "Events" ], "summary": "Document.Receive.Delivered", "description": "Document delivered\n\nThe `event` field in the JSON body is `Document.Receive.Delivered`.\n\nSent as a POST request to the URL configured in your webhook settings.", "security": [ {} ], "parameters": [ { "name": "Signature", "in": "header", "required": true, "description": "HMAC-SHA256 hex digest of the raw JSON request body, using your webhook secret as the key.", "schema": { "type": "string" }, "example": "38b3a292d88f8eca9c6fe9bb7bb17bb3104c56e6e171e917711585e577fefd42" }, { "name": "Timestamp", "in": "header", "required": true, "description": "The UNIX timestamp of the request, in seconds.", "schema": { "type": "string" }, "example": 1681234567 } ], "requestBody": { "required": true, "description": "JSON body delivered to your webhook URL.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEnvelopeDocumentReceiveDelivered" } } } }, "responses": { "200": { "description": "Your endpoint should return 2xx to acknowledge receipt." } } } } } }