Standard 2.0 · event-driven
Message standard & test lab
42 messages in one signed event envelope, 55 shared code lists (1,322 values), numbered business rules and 36 end-to-end scenarios, from a simple order to recalls, re-exports and failed deliveries. Read the implementation guides.
Event envelope (CloudEvents-style)
Every message travels in this envelope. Delivery is at-least-once, ordered per sender + subject, signed with HMAC-SHA256 and acknowledged synchronously.
| Field | Type | Req | Description | Code list / format | EDI / GS1 / SAP mapping |
|---|---|---|---|---|---|
| specversion | string | yes | NutraB2B spec version. Must be 2.0. | x12: GS08 version edifact: UNH S009 version/release | |
| id | string | yes | Globally unique event id (UUID v4/v7 or ULID). Never reused. | x12: ST02 control number edifact: UNH 0062 message ref | |
| type | string | yes | Event type: nutrab2b.<family>.<event>.v2 | ^nutrab2b\.[a-z_]+\.[a-z_]+\.v2$ | x12: ST01 transaction set id edifact: UNH S009 message type |
| source | string | yes | URI of the sending system | ||
| subject | string | yes | Business key the event is about (PO number, lot, SSCC…). Ordering is guaranteed per subject. | ||
| time | datetime | yes | When the business event happened (RFC 3339 with offset) | x12: GS04/GS05 edifact: UNB 0017/0019 | |
| datacontenttype | string | Always application/json | |||
| dataschema | string | URI of the JSON Schema for data | |||
| sender | object | yes | Who sends the event | ||
| gln | string | yes | GS1 Global Location Number of the legal party | ^\d{13}$ | x12: ISA06/ISA08 + N104 (qualifier UL) edifact: UNB 0004/0010, NAD C082 (agency 9) gs1: sender/receiver Identifier Authority=GS1 |
| lei | string | ISO 17442 Legal Entity Identifier | ^[A-Z0-9]{18}\d{2}$ | ||
| duns | string | D-U-N-S number | ^\d{9}$ | ||
| name | string | Legal name (informational) | |||
| receiver | object | yes | Who must process the event | ||
| gln | string | yes | GS1 Global Location Number of the legal party | ^\d{13}$ | x12: ISA06/ISA08 + N104 (qualifier UL) edifact: UNB 0004/0010, NAD C082 (agency 9) gs1: sender/receiver Identifier Authority=GS1 |
| lei | string | ISO 17442 Legal Entity Identifier | ^[A-Z0-9]{18}\d{2}$ | ||
| duns | string | D-U-N-S number | ^\d{9}$ | ||
| name | string | Legal name (informational) | |||
| correlationid | string | yes | Shared by every event in one business conversation (RFQ → … → remittance) | ||
| causationid | string | id of the event that caused this one (e.g. PO response → PO) | |||
| idempotencykey | string | yes | Receiver processes each key once; re-sends return the first acknowledgement | ||
| sequence | integer | yes | Monotonic per sender + subject, starting at 1. Gaps are parked until filled. | ||
| env | string | yes | test or prod | ||
| signature | object | Optional detached signature. Webhooks additionally carry X-NB2B-Signature (HMAC). | |||
| alg | string | yes | JWS algorithm (ES256, EdDSA, RS256) or HMAC-SHA256 | ||
| kid | string | yes | Key id published in the sender's JWKS | ||
| value | string | yes | Detached JWS over the canonical body (RFC 7515 Appendix F) | ||
| attachments | array<object> | Large documents travel by reference, never inline | |||
| doc_type | string | yes | Kind of document | ||
| uri | string | yes | HTTPS or object-store URI; signed URLs valid ≥ 7 days | ||
| sha256 | string | yes | Hex SHA-256 of the file | ^[a-f0-9]{64}$ | |
| media_type | string | e.g. application/pdf |
Max event
1 MB
Max batch
10 MB
Signature window
300 s
Retries then DLQ
7 attempts