Create webhook responses

Possible responses when creating a webhook:

Status	Meaning	Description
201	Created	Webhook created successfully. Header values are always masked in the response.
401	Unauthorized	The API returns this when the API key given doesn’t match a valid merchant account.
403	Forbidden	The API returns this when the API secret doesn’t have the required permission.
422	Unprocessable Entity	The API returns this when validation fails. It returns only one error per request—validations run in order and short-circuit on the first failure.

To perform this operation, authenticate with an authentication token.

Examples

Successful create webhook response

{
  "webhook": {
    "publishable_id": "twhs_abc123xyz",
    "webhook_url": "https://example.com/shippit-webhook",
    "enabled_states": ["ready_for_pickup", "in_transit", "completed"],
    "hide_delivery_address": false,
    "hide_receiver_details": false,
    "enabled": true,
    "headers": [
      { "key": "X-Custom-Token", "value": "*****" }
    ]
  }
}

Custom header values are always masked (*****) in all responses—they’re write-only.

Failed create webhook responses

Returned when validation fails. All validation errors follow the same shape:

{
  "error": "invalid_resource",
  "error_description": "<message>"
}

Trigger	Error Description
Merchant already has 6 webhooks	Maximum number of webhooks reached.
Webhook URL is blank or doesn’t start with http(s)://	Please enter a valid URL starting with http:// or https://
Webhook URL exceeds 2048 characters	Webhook URL must not exceed 2048 characters.
Enabled states is empty	Add minimum one enabled state.
Enabled states contains unknown values	One or more enabled states are invalid.
More than 6 headers provided	You can add up to 6 custom headers.
A header key is blank or contains whitespace	Please enter a valid key without whitespaces
A header value is blank	Header value can’t be empty.
Duplicate header key	Header key can’t be duplicated.

Unknown error occurs

Shippit may return this if it has trouble with the combination of the input or merchant account configuration.

{
  "error": "system",
  "error_description": "An unknown error has occurred."
}