Webhooks Guide

Webhooks push TradeAware events to your systems in real time, eliminating polling and exports. They enable instant information and automated workflows, with built-in retries and monitoring.

PreviousAPI Access and Business Account Registration NextAuthentication

Last updated 2 days ago

Webhooks Guide

Webhooks push TradeAware events to your systems in real time, eliminating polling and exports. They enable instant information and automated workflows, with built-in retries and monitoring.

Prerequisites

Webhooks is a premium feature in TradeAware. To use this functionality, your account must be enabled for this. If you do not have this enabled, contact your Customer Success Manager.

Accessing Webhooks in the Web App

Click the profile / settings icon at the bottom‑left corner of the side‑bar and choose Manage account.
The Manage account page shows your personal & business details and a Developer Tools section.
Inside Developer Tools you will find two entries:
1. API Access – create or revoke access tokens.
2. Webhooks – configure event callbacks.

Selecting Developer Tools → Webhooks opens the page shown below.

The Webhook page shows every webhook you’ve created:

URL – the destination endpoint that will receive event payloads.
Error rate – the percentage of recent deliveries that returned a non-2xx HTTP status (0 % means everything is healthy).
Status – Active webhooks send events immediately; Inactive ones are paused but not deleted.

Create a Webhook

Click Add data or the ➕ button to open the creation form.

Fill in three fields:

URL – must be a public HTTPS endpoint (e.g. https://webhook.site/abc123).
Events – choose one or more event types.
Description – optional note such as “QA inbox”.

Opening the Events dropdown shows the current set of event types:.

Key event types

`transaction.updated`

A message is sent every time a transaction moves to a new status.

DRAFT – the transaction is still being edited and not yet queued.
TO_SUBMIT – ready to be sent to EU TRACES.
SUBMITTED – delivered to TRACES, awaiting validation.
ERROR - the transaction has been rejected by the EU Information System.
AVAILABLE – accepted by TRACES and now carries reference and verification numbers.

Typical automation: Notify an ERP system when a transaction reaches AVAILABLE so that a Reference and Verification number can be added to a transaction and it can be released.

`business_invitation.updated`

Triggers whenever a buyer or supplier acts on a business invitation.

ACCEPTED – other party accepted; access granted.
REJECTED – other party declined.
CANCELLED – sender cancelled the invitation.

Typical automation: Post to Slack when an invite is ACCEPTED so your onboarding team can proceed.

`analysis.precision.updated`

Notifies you about the state of a TradeAware Precision deforestation analysis.

SUCCEEDED – results are available (risk scores, deforestation %, overlap layer).
FAILED – analysis could not complete.

Typical automation: Notify sustainability teams when a high‑risk Precision result is COMPLETED so they can initiate supplier engagement.

Webhook list

The Webhook page shows every webhook you’ve created:

URL – the destination endpoint that will receive event payloads.
Error rate – the percentage of recent deliveries that returned a non-2xx HTTP status (0 % means everything is healthy).
Status – Active webhooks send events immediately; Inactive ones are paused but kept for later.

Use the ➕ button to add a new webhook. Hover on any row and click ⁝ to edit settings, delete the webhook, or send a test message.

Webhook details page

Shows the full URL of the webhook and your optional Description.
Status badge tells you if deliveries are Active or Inactive.
Listening for displays how many event types the hook subscribes to; hover to see each one.
Click the eye to copy the Signing secret for HMAC verification.
Last message attempts lists the latest deliveries with status, event type, timestamp, and a See the response link for debugging.
Send test message fires sample events on demand, great for QA.
Use Delete to remove the webhook permanently or Cancel to return to the list without changes.

Security Best Practice: Verify Webhook Payloads

To ensure the integrity and authenticity of incoming webhook data, it's crucial to verify the signature of each payload before processing it. TradeAware uses Svix to sign all webhook events. You can verify these signatures using one of two methods:

Using Official Svix Libraries: This is the recommended approach for most users. Svix provides client libraries for various programming languages that simplify the verification process.
Manual Verification: If you prefer or need to implement the verification logic yourself without a Svix library, you can follow their manual recipe.

Always verify the svix-id, svix-timestamp, and svix-signature headers as described in the Svix documentation to protect against replay attacks and ensure the payload hasn't been tampered with.

Frequently Asked Questions

Can I use HTTP instead of HTTPS? No. Webhooks require HTTPS for security.
What happens if my server is down? TradeAware retries failed deliveries for up to 24 hours. Persistent failures raise the Error rate so that will you be aware this is happening.
How do I pause deliveries without deleting the hook? Edit the webhook and toggle its status to Inactive.
Where can I see the full list of available events? Either open the Events dropdown in the creation form or call GET /webhooks/events from the API.
What happens if my endpoint keeps failing? If all attempts to a specific endpoint fail for a period of 5 days, the endpoint will be disabled. You'll have to re-add it to enable it again.

PreviousAPI Access and Business Account Registration NextAuthentication

Last updated 2 days ago

Prerequisites

Webhooks is a premium feature in TradeAware. To use this functionality, your account must be enabled for this. If you do not have this enabled, contact your Customer Success Manager.

Accessing Webhooks in the Web App

Click the profile / settings icon at the bottom‑left corner of the side‑bar and choose Manage account.
The Manage account page shows your personal & business details and a Developer Tools section.
Inside Developer Tools you will find two entries:
1. API Access – create or revoke access tokens.
2. Webhooks – configure event callbacks.

Selecting Developer Tools → Webhooks opens the page shown below.

The Webhook page shows every webhook you’ve created:

URL – the destination endpoint that will receive event payloads.
Error rate – the percentage of recent deliveries that returned a non-2xx HTTP status (0 % means everything is healthy).
Status – Active webhooks send events immediately; Inactive ones are paused but not deleted.

Create a Webhook

Click Add data or the ➕ button to open the creation form.

Fill in three fields:

URL – must be a public HTTPS endpoint (e.g. https://webhook.site/abc123).
Events – choose one or more event types.
Description – optional note such as “QA inbox”.

Opening the Events dropdown shows the current set of event types:.

Key event types

`transaction.updated`

A message is sent every time a transaction moves to a new status.

DRAFT – the transaction is still being edited and not yet queued.
TO_SUBMIT – ready to be sent to EU TRACES.
SUBMITTED – delivered to TRACES, awaiting validation.
ERROR - the transaction has been rejected by the EU Information System.
AVAILABLE – accepted by TRACES and now carries reference and verification numbers.

Typical automation: Notify an ERP system when a transaction reaches AVAILABLE so that a Reference and Verification number can be added to a transaction and it can be released.

`business_invitation.updated`

Triggers whenever a buyer or supplier acts on a business invitation.

ACCEPTED – other party accepted; access granted.
REJECTED – other party declined.
CANCELLED – sender cancelled the invitation.

Typical automation: Post to Slack when an invite is ACCEPTED so your onboarding team can proceed.

`analysis.precision.updated`

Notifies you about the state of a TradeAware Precision deforestation analysis.

SUCCEEDED – results are available (risk scores, deforestation %, overlap layer).
FAILED – analysis could not complete.

Typical automation: Notify sustainability teams when a high‑risk Precision result is COMPLETED so they can initiate supplier engagement.

Webhook list

The Webhook page shows every webhook you’ve created:

URL – the destination endpoint that will receive event payloads.
Error rate – the percentage of recent deliveries that returned a non-2xx HTTP status (0 % means everything is healthy).
Status – Active webhooks send events immediately; Inactive ones are paused but kept for later.

Use the ➕ button to add a new webhook. Hover on any row and click ⁝ to edit settings, delete the webhook, or send a test message.

Webhook details page

Shows the full URL of the webhook and your optional Description.
Status badge tells you if deliveries are Active or Inactive.
Listening for displays how many event types the hook subscribes to; hover to see each one.
Click the eye to copy the Signing secret for HMAC verification.
Last message attempts lists the latest deliveries with status, event type, timestamp, and a See the response link for debugging.
Send test message fires sample events on demand, great for QA.
Use Delete to remove the webhook permanently or Cancel to return to the list without changes.

Security Best Practice: Verify Webhook Payloads

Using Official Svix Libraries: This is the recommended approach for most users. Svix provides client libraries for various programming languages that simplify the verification process.
Instructions & Examples:
Manual Verification: If you prefer or need to implement the verification logic yourself without a Svix library, you can follow their manual recipe.
Manual Instructions:

Always verify the svix-id, svix-timestamp, and svix-signature headers as described in the Svix documentation to protect against replay attacks and ensure the payload hasn't been tampered with.

Frequently Asked Questions

Can I use HTTP instead of HTTPS? No. Webhooks require HTTPS for security.
What happens if my server is down? TradeAware retries failed deliveries for up to 24 hours. Persistent failures raise the Error rate so that will you be aware this is happening.
How do I pause deliveries without deleting the hook? Edit the webhook and toggle its status to Inactive.
Where can I see the full list of available events? Either open the Events dropdown in the creation form or call GET /webhooks/events from the API.
What happens if my endpoint keeps failing? If all attempts to a specific endpoint fail for a period of 5 days, the endpoint will be disabled. You'll have to re-add it to enable it again.