Webhook map
notificationsdelivery(notifications.delivery)
HTTP handler setup
app/api/webhook/route.ts
import { processWebhook } from "corsair";
import { corsair } from "@/server/corsair";
export async function POST(request: Request) {
const headers = Object.fromEntries(request.headers);
// With multiTenancy, give each tenant its own URL (/api/webhook?tenantId=acme):
// the query says whose account, secret and hooks handle the delivery.
const query = Object.fromEntries(new URL(request.url).searchParams);
// The raw text, not request.json(): signatures are checked over the exact bytes sent.
const body = await request.text();
const result = await processWebhook(corsair, headers, body, query);
if (!result.plugin) {
return Response.json({ success: false }, { status: 404 });
}
// A refusal (bad signature) carries no status and answers 400; a handler
// that threw comes back with 500, so the sender retries it.
const status =
result.response?.success === false ? (result.response.statusCode ?? 400) : 200;
return Response.json(result.response ?? { success: true }, {
status,
headers: result.responseHeaders,
});
}
Events
Notifications
Delivery
notifications.delivery
A Shippo webhook delivery: the { event, test, data } envelope whose data is the full track, transaction or batch object
Payload
| Name | Type | Required | Description |
|---|---|---|---|
event | string | Yes | — |
test | boolean | null | No | — |
data | object | null | No | — |
data full type
data full type
{
carrier?: string | null,
tracking_number?: string | null,
address_from?: {
city?: string | null,
state?: string | null,
zip?: string | null,
country?: string | null
} | null,
address_to?: {
city?: string | null,
state?: string | null,
zip?: string | null,
country?: string | null
} | null,
eta?: string | null,
original_eta?: string | null,
servicelevel?: {
name?: string | null,
token?: string | null,
terms?: string | null,
extended_token?: string | null,
parent_servicelevel?: {
name?: string | null,
token?: string | null,
terms?: string | null,
extended_token?: string | null
} | null
} | null,
messages?: string[] | null,
metadata?: string | null,
tracking_status?: {
object_id?: string | null,
object_created?: string | null,
object_updated?: string | null,
status?: string | null,
status_date?: string | null,
status_details?: string | null,
substatus?: {
code?: string | null,
text?: string | null,
action_required?: boolean | null
} | null,
location?: {
city?: string | null,
state?: string | null,
zip?: string | null,
country?: string | null
} | null
} | null,
tracking_history?: {
object_id?: string | null,
object_created?: string | null,
object_updated?: string | null,
status?: string | null,
status_date?: string | null,
status_details?: string | null,
substatus?: {
code?: string | null,
text?: string | null,
action_required?: boolean | null
} | null,
location?: {
city?: string | null,
state?: string | null,
zip?: string | null,
country?: string | null
} | null
}[] | null
} | {
object_id?: string | null,
object_owner?: string | null,
object_created?: string | null,
object_updated?: string | null,
object_state?: string | null,
status?: string | null,
rate?: string | {
object_id?: string | null,
amount?: string | null,
currency?: string | null,
amount_local?: string | null,
currency_local?: string | null,
provider?: string | null,
carrier_account?: string | null,
servicelevel_name?: string | null,
servicelevel_token?: string | null
} | null,
parcel?: string | null,
label_url?: string | null,
commercial_invoice_url?: string | null,
qr_code_url?: string | null,
label_file_type?: string | null,
tracking_number?: string | null,
tracking_status?: string | null,
tracking_url_provider?: string | null,
eta?: string | null,
messages?: {
source?: string | null,
code?: string | null,
text?: string | null
}[] | null,
metadata?: string | null,
test?: boolean | null
} | {
object_id?: string | null,
object_owner?: string | null,
object_created?: string | null,
object_updated?: string | null,
status?: string | null,
default_carrier_account?: string | null,
default_servicelevel_token?: string | null,
label_filetype?: string | null,
metadata?: string | null,
label_url?: string[] | null,
batch_shipments?: {
next?: string | null,
previous?: string | null,
results?: {
object_id?: string | null,
shipment?: string | null,
transaction?: string | null,
status?: string | null,
carrier_account?: string | null,
servicelevel_token?: string | null,
messages?: (string | {
source?: string | null,
code?: string | null,
text?: string | null
})[] | null,
metadata?: string | null
}[] | null
} | null,
object_results?: {
purchase_failed?: number | null,
purchase_succeeded?: number | null
} | null,
test?: boolean | null
} | null
Response data full type
Response data full type
{
event: string,
test?: boolean | null,
data?: {
carrier?: string | null,
tracking_number?: string | null,
address_from?: {
city?: string | null,
state?: string | null,
zip?: string | null,
country?: string | null
} | null,
address_to?: {
city?: string | null,
state?: string | null,
zip?: string | null,
country?: string | null
} | null,
eta?: string | null,
original_eta?: string | null,
servicelevel?: {
name?: string | null,
token?: string | null,
terms?: string | null,
extended_token?: string | null,
parent_servicelevel?: {
name?: string | null,
token?: string | null,
terms?: string | null,
extended_token?: string | null
} | null
} | null,
messages?: string[] | null,
metadata?: string | null,
tracking_status?: {
object_id?: string | null,
object_created?: string | null,
object_updated?: string | null,
status?: string | null,
status_date?: string | null,
status_details?: string | null,
substatus?: {
code?: string | null,
text?: string | null,
action_required?: boolean | null
} | null,
location?: {
city?: string | null,
state?: string | null,
zip?: string | null,
country?: string | null
} | null
} | null,
tracking_history?: {
object_id?: string | null,
object_created?: string | null,
object_updated?: string | null,
status?: string | null,
status_date?: string | null,
status_details?: string | null,
substatus?: {
code?: string | null,
text?: string | null,
action_required?: boolean | null
} | null,
location?: {
city?: string | null,
state?: string | null,
zip?: string | null,
country?: string | null
} | null
}[] | null
} | {
object_id?: string | null,
object_owner?: string | null,
object_created?: string | null,
object_updated?: string | null,
object_state?: string | null,
status?: string | null,
rate?: string | {
object_id?: string | null,
amount?: string | null,
currency?: string | null,
amount_local?: string | null,
currency_local?: string | null,
provider?: string | null,
carrier_account?: string | null,
servicelevel_name?: string | null,
servicelevel_token?: string | null
} | null,
parcel?: string | null,
label_url?: string | null,
commercial_invoice_url?: string | null,
qr_code_url?: string | null,
label_file_type?: string | null,
tracking_number?: string | null,
tracking_status?: string | null,
tracking_url_provider?: string | null,
eta?: string | null,
messages?: {
source?: string | null,
code?: string | null,
text?: string | null
}[] | null,
metadata?: string | null,
test?: boolean | null
} | {
object_id?: string | null,
object_owner?: string | null,
object_created?: string | null,
object_updated?: string | null,
status?: string | null,
default_carrier_account?: string | null,
default_servicelevel_token?: string | null,
label_filetype?: string | null,
metadata?: string | null,
label_url?: string[] | null,
batch_shipments?: {
next?: string | null,
previous?: string | null,
results?: {
object_id?: string | null,
shipment?: string | null,
transaction?: string | null,
status?: string | null,
carrier_account?: string | null,
servicelevel_token?: string | null,
messages?: (string | {
source?: string | null,
code?: string | null,
text?: string | null
})[] | null,
metadata?: string | null
}[] | null
} | null,
object_results?: {
purchase_failed?: number | null,
purchase_succeeded?: number | null
} | null,
test?: boolean | null
} | null
}
webhookHooks example
shippo({
webhookHooks: {
notifications: {
delivery: {
before(ctx, args) {
return { ctx, args };
},
after(ctx, response) {
},
},
},
},
})