Subscribe to an HTS code

Follow the duty treatment of an HTS code for a list of origins into one destination. Requires the tariff-subscriptions:write scope.

How delivery works

• Once a day every leaf tariff line × origin is re-evaluated. When anything differs from what was last delivered, the subscription's webhook receives one tariff.changed call listing every change. Nothing is sent when nothing changed.
• The treatment at creation (and for an origin added later) is the starting point and is not sent. Read it with GET /tariff-subscriptions/{subscriptionId}.
• A change is anything that decides the duty: the base rate, a Chapter 99 additional duty added, removed or re-rated, a Section 232 metal duty, an import prohibition, a claimable exclusion, or the tariff line itself being added, removed or re-described. A new HTS revision that restates the same duties is not a change.
• Delivery is at least once. A delivery that does not answer 2xx is retried within the day with everything since the last successful one. The webhook is disabled after 10 failures in a row spanning more than 24 hours.
• Every delivery carries X-Wove-Delivery-Id. The same evaluation sent twice carries the same id; answer 2xx to an id you have already processed and ignore it.
• A body is capped at 256 KB / 500 changes. Past that it sets truncated: true and totalChanges; read the rest from GET /tariff-subscriptions/{subscriptionId}.
• Each change carries its changes details. The full previous / current treatment is included only when the subscription sets includeTreatments: true.

Verifying a delivery

X-Wove-Signature is the hex HMAC-SHA256 of the raw request body, keyed with the webhook secret:

const expected = crypto.createHmac('sha256', secret).update(rawBody).digest('hex')
const valid = crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(req.headers['x-wove-signature']))

Example payload

{
  "event": "tariff.changed",
  "timestamp": "2026-07-15T06:00:04.112Z",
  "data": {
    "subscriptionId": "1641343378340540417",
    "subject": { "hsCode": "22042120", "destinationCountry": "US", "originCountries": ["CA", "FR"] },
    "evaluatedFor": "2026-07-15",
    "changes": [
      {
        "kind": "scheduled",
        "effectiveDate": "2026-09-29",
        "lineCode": "2204.21.20.00",
        "originCountry": "CA",
        "changes": [
          { "type": "additional_duty.removed", "key": "9903.03.12|full" },
          { "type": "prohibition.added", "key": "section_338|2026-09-29||" }
        ],
        "previous": { "lineCode": "2204.21.20.00", "...": "full TariffTreatment, with includeTreatments" },
        "current": { "lineCode": "2204.21.20.00", "...": "full TariffTreatment, with includeTreatments" }
      }
    ]
  }
}