Webhooks Guide

⚠️ 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

1. Click the profile / settings icon at the bottom‑left corner of the side‑bar and choose Manage account.

2. The Manage account page shows your personal & business details and a Developer Tools section.

3. 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 – any public HTTPS endpoint that accepts POST requests (e.g. your own https://api.example.com/webhooks, or a testing service such as https://webhook.site/abc123).

• Events – choose one or more event types.

• Description – optional note such as “QA inbox”.

webhook.site is shown only for quick testing. It is an external service not operated by LiveEO and may apply usage limits or paid plans. Use any HTTPS endpoint you control in production.

Use tools like webhook.site, ngrok, or RequestBin for development. For production, use your own HTTPS endpoint and verify signatures (see Security).

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

These verification steps apply no matter which endpoint provider you use – self-hosted, cloud-function, or third-party.

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:

1. 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.

2. Instructions & Examples: https://docs.svix.com/receiving/verifying-payloads/how

3. Manual Verification: If you prefer or need to implement the verification logic yourself without a Svix library, you can follow their manual recipe.

4. Manual Instructions: https://docs.svix.com/receiving/verifying-payloads/how-manual

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

• Do I have to use webhook.site? No. It’s only an example

• Does the integration need a paid webhook.site plan? No. The free tier is fine for testing.

• What are the minimum requirements for my own endpoint? It must be publicly reachable via HTTPS, accept POST requests, return a 2xx on success, and verify the Svix signature.

• 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.