Receiving webhooks

Teak sends webhooks to your server when something happens to an order after checkout. For example, protection is issued or voided, or a customer files a refund request. Use them to keep your records, customer service tools, and refunds in step with Teak.

Two webhooks are required to go live:

Contract Issued: confirms protection was issued, so you can record it and reconcile your invoice.
Contract Void: tells you when protection is removed, so you can refund the customer.

If customers can exchange items, Contract Downgraded is also required.

Every event, with when it fires and an example payload, is in the Contract events and Refund request events reference.

How it works

You add a webhook subscription in the Teak Dashboard: an endpoint URL, a secret, and the events you want.
When a subscribed event happens, Teak sends a POST request to your URL with a JSON body.
Your server verifies the signature, stores the event, and responds with a 2xx status.

Every webhook has the same envelope:

{
  "resource": "Policy",
  "action": "Voided",
  "data": { }
}

Field	Description
`resource`	What the event is about: `Policy` for contract events or `Claim` for refund request events.
`action`	What happened, for example `Issued`, `Voided`, or `Pending_Documents`.
`data`	The contract or refund request, in its state after the event.

Action values are case-sensitive

They use underscores, for example On_Hold and Pending_Id_Verification. Match them exactly.

Set up a subscription

Open Notifications in the Teak Dashboard. For sandbox, use dashboard.sandbox.helloteak.com/notifications.
Add a subscription with:
- Webhook URL: an HTTPS endpoint on your server.
- Secret: a random string of at least 32 characters. Teak uses it to sign every request. Without a secret, requests aren't signed and you can't verify that they came from Teak.
- Events: the events to send to this URL.
Optionally add an email address to also receive each event by email.

You can create more than one subscription, for example one per environment or one per event group.

Delivery

Timing. Teak delivers webhooks in batches every minute. Expect an event within about two minutes of it happening. If events are delayed, check status.helloteak.com.
Request. POST with Content-Type: application/json. The signature is in the X-Protecht-Signature header.
Timeout. Respond within 10 seconds. Store the event and respond first, then do slow work (sending emails, calling other services) afterwards.
Retries. If Teak can't connect to your endpoint, or it doesn't respond within 10 seconds, Teak retries up to four more times over about 35 minutes: immediately, then after 1, 5, and 30 minutes. After that the event is dropped.
Responses count as delivered. Teak treats any HTTP response as delivered, including 4xx and 5xx. Returning an error does not cause a retry, so don't rely on it to get an event resent.

Handle duplicates and out-of-order events

Retries mean you can receive the same event more than once, and events for the same order can arrive in any order. Webhooks don't include an event ID, so:

Treat the combination of resource, action, and the record's ID (data.policy_number for contracts, data.claim_number for refund requests) as the event's identity, and ignore repeats.
Use data.status and data.updated to decide the current state, rather than the order in which events arrive.

Match webhooks to your orders

Contract events identify the order in two ways:

Field	Value
`data.order_number`	The `reference_id` you sent to Submit an order.
`data.protecht_order_id`	The Teak order ID. For orders from the widget, this is the same as the `session_id` you submitted.

Refund request events use data.external_reference_id for your order number and data.order_number for the Teak order ID. See Refund request events.

Test your integration

Create a subscription in the sandbox dashboard pointing at your endpoint. To inspect raw requests first, you can point it at a request inspector.
Submit a sandbox order through the widget. You should receive a Policy / Issued event for each protected item.
Ask your Teak integration contact to void, cancel, or change a contract, or to create a refund request, to trigger the other events you subscribe to.
Check that your endpoint rejects a request with a wrong signature.

Try it locally

The webhooks example, in Node.js or Python, verifies signatures, ignores repeats, and refunds voided contracts. It includes a script that sends signed test events, so you can try your endpoint before real webhooks arrive.

Next steps

Next, secure your endpoint and choose your events:

Verify webhook signatures so you only act on webhooks that came from Teak.
Handle contract events and refund request events: what to do when each one arrives.