Ingest a webhook event

post

https://app.shipscience.com/webhooks/v1/ingest/{webhook_api_key}

Accepts a shipment or label event from an integration partner.

Authentication

URL path: opaque per-credential webhook_api_key. We mint this for
you; treat it as semi-public (it identifies your credential but is
not a secret on its own — HMAC over the body is the cryptographic auth).
Body: HMAC-SHA256 over the raw request body, base64-encoded. Send
it in the signature header required by your configured adapter:
- Conformant default adapter — X-ShipScience-Signature.
- Partner native adapter — uses its own signature header;
  refer to your partner's documentation for the exact name.
  The server verifies only the header for your credential's adapter;
  a missing or invalid signature returns 401.

Request body

The body shape depends on the adapter configured on your credential:

Conformant adapter — JSON envelope { event_id, event_type, occurred_at, data } (see webhook_envelope_shipment). Send this
shape unless you have a partner native adapter.
Partner native adapter — send your provider's webhook payload
as-is (see webhook_envelope_partner_native); ShipScience maps
the fields per-credential. Refer to your partner's documentation
for the authoritative schema. The conformant envelope is not
accepted by a native-adapter credential.
Sending the wrong shape for your adapter returns 422.

Idempotency

Same event_id = same event. Resending is a no-op (we respond 200).
We accept the same event_id forever; safe to retry indefinitely.
Do not back off on 200 responses for "duplicate" — they are accepted.

Retry & timing

We respond <500 ms typical, <2 s worst case.
2xx = accepted, will be processed; 4xx = don't retry; 5xx = retry with backoff.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Path Params

webhook_api_key

string

required

Per-credential opaque token. Provided to you at onboarding.

Body Params

Conformant adapter envelope. This is the shape ShipScience expects
for credentials configured with the default ("Conformant") adapter.
Partner native adapters use their own provider-specific shape —
see webhook_envelope_partner_native and the per-adapter section
in the endpoint description.

event_id

string

required

Unique per event. Used for idempotency — resending the same event_id is a no-op.

event_type

string

enum

required

Allowed:

occurred_at

date-time

required

data

object

required

The shipment payload. Identify the manifest shipment with one of:
api_id (ours, returned from a prior webhook), external_id
(yours, partner-supplied), or tracking_number. On update, send
one of those plus the fields you want to change. Omitted fields
preserve their existing value; explicit nulls null the column.

items is the COMPLETE current state of items on this manifest:
items present in a previous payload but absent here are deleted
automatically. Each item must be identified by either api_id
(ours, returned on a prior webhook) or external_id (yours);
an item without either cannot be reconciled and is rejected.

Item updates are partial: an item identified by api_id/external_id
that omits title, sku, etc. preserves the existing values. New
items (no matching api_id/external_id) require title so we
have something to persist as item_description.

order_number must be present on the manifest at the moment items
are reconciled — either supplied in this payload or already
persisted from a prior payload. A payload that introduces items on
a manifest with no prior order_number and no order_number in
the current body will be rejected.

Headers

X-ShipScience-Signature

string

Base64-encoded HMAC-SHA256 over the raw request body. Send for the conformant default adapter. Partner native adapters use their own signature header — see endpoint description.

Responses

200

Event accepted.

401

Unknown webhook_api_key OR invalid signature.

422

Malformed body, missing event_id, or unsupported event_type.