Subscribe Webhooks
POST/api/shippo/instances/:integration_instance/webhooks/subscribe
Registers (or re-registers) this instance's webhook URL at Shippo — one registration per subscribed event. Webhooks are registered automatically on connect; use this to repair a missing registration. Runs synchronously.
This endpoint currently requires session authentication; Personal Access Token scope support is in progress.
No body. Returns 200 with the resulting status. The status lists each event SKU.io subscribes to (transaction_created, transaction_updated, track_updated) with whether it is registered at Shippo, its Shippo webhook id, active and is_test flags; plus webhook_url (this instance's inbound URL), subscribed (all events registered), subscribed_at, last_webhook_received_at, failed_event_count and signature_verification (whether HMAC signatures are verified for this instance). Returns 422 with code invalid_token when Shippo rejects the API token, or api_error for other Shippo failures. Returns 404 for an unknown instance.
Authentication: Requires a Bearer token.
Request
Responses
- 200
- 401
- 403
- 404
- 422
- 429
OK
Response Headers
Unauthenticated — the bearer token is missing, revoked, expired, or malformed. Never retry automatically; fix the credential. See the Errors guide.
Forbidden — the token lacks a required scope, the endpoint is not available to API tokens, or the user behind the token lacks the permission. A human must adjust the token scopes or user permissions; do not retry.
Not Found
Response Headers
Unprocessable Entity
Response Headers
Rate limited — platform limit is 1,000 requests/min; individual tokens may carry lower limits. Honor the Retry-After header before retrying. See the Rate Limits guide.