# receiveWebhookCallback

Webhook Callback Endpoint

`POST /webhook/callback`

**API:** Avalara Item Classification API
**Tag:** WebhookCallback
**API Version:** 16.0.1-oas3
**Base URL:** https://api-sandbox.classification.avalara.net
**Authentication:** Basic (username + license key)

Source: https://developer.avalara.com/products/managed-and-premium-tariff-code/api/methods/WebhookCallback/receiveWebhookCallback/

## Description

This is the endpoint that clients need to implement to receive webhook callbacks when classifications are completed.
Only clients who have specifically opted to receive webhook callbacks need to implement this endpoint.

**Authentication:**
The webhook callback supports two authentication methods:
- Basic Authentication: Avalara will send an Authorization header with "Basic {token}"
- OAuth: Avalara will send an Authorization header with "Bearer {token}"

**Response Requirements:**
- The endpoint should return HTTP 200 or 201 on success
- The recommended response format is: {"name":"API_RESPONSE","value":"SUCCESSFUL"}
- For errors, return HTTP 400 with: {"name":"API_RESPONSE","value":"ERROR"}

**Retry Behavior:**
If the webhook call fails due to server connectivity issues, the system will automatically retry the call.
Clients should ensure their webhook endpoint is reliable and responds quickly to avoid retry delays.

## Request Body

**Content-Type:** `application/json; charset=utf-8`
**Schema:** `WebhookCallbackRequest`

The webhook callback payload that will be sent to the client's webhook endpoint when a classification is completed.
Only clients who have specifically opted to receive webhook callbacks need to implement this endpoint.
This is an optional feature for "Item Classification Without Storage" customers.

**Authentication:**
The webhook callback supports two authentication methods:
- Basic Authentication: Requires an API key configured in the Avalara system
- OAuth: Requires an OAuth token endpoint to be configured in the Avalara system

**Conditional Fields:**
- The `possibleHsCodes` field is only included when the `broker` parameter is set to "true" and there are alternative HS codes available

**Retry Behavior:**
If the webhook call fails due to server connectivity issues, the system will automatically retry the call.

| Property | Type | Required | Description |
|---|---|---|---|
| `hsClassificationId` | string | **Yes** | The id of the HS classification request that was completed. Example: `1234-SKU001-CA`. |
| `companyId` | string | **Yes** | The ID of the company that owns this item. Example: `3402`. |
| `itemCode` | string | **Yes** | The unique item code (typically your SKU) that was classified. Example: `ABC123`. |
| `countryOfDestination` | string | **Yes** | The country code for which the classification was performed. Example: `CA`. |
| `status` | string | **Yes** | The status of the classification request. Values: `CLASSIFIED`, `CANNOT_BE_CLASSIFIED`. Example: `CLASSIFIED`. |
| `hsCode` | string | No | The HS classification result. Example: `320250`. |
| `rationale` | string | No | Explanation of the classification decision when available. Example: `This item is classified as a night gown based on its material composition and intended use.`. |
| `possibleHsCodes` | string | No | Alternative HS codes that could apply to this item, when available.
This is provided as a stringified JSON array. Example: `["320250", "320251", "320252"]`. |
| `compliance` | object | No | Compliance information if compliance_flagging was enabled. |

## Responses

| Status | Description | Schema |
|---|---|---|
| 200 | Webhook received successfully |  |
| 201 | Webhook received and processed successfully (preferred response) |  |
| 400 | Bad request - invalid payload |  |

## Example Request

```bash
curl -X POST "https://api-sandbox.classification.avalara.net/webhook/callback" \
  -H "Authorization: Basic <credentials>" \
  -H "Accept: application/json" \
  -d '{
  "hsClassificationId": "1234-SKU001-CA",
  "companyId": "3402",
  "itemCode": "ABC123",
  "countryOfDestination": "CA",
  "status": "CLASSIFIED",
  "hsCode": 320250,
  "rationale": "This item is classified as a night gown based on its material composition and intended use.",
  "possibleHsCodes": "[\"320250\", \"320251\", \"320252\"]",
  "compliance": {}
}'
```