Webhooks

Receive real-time notifications about events in your Heydeo account.

Overview

Webhooks allow you to receive HTTP callbacks when specific events occur in your account. Instead of polling the API, Heydeo will push event data to your specified endpoint in real-time.

💡 Tip: Webhooks are ideal for automating workflows, syncing data, and triggering actions based on shipment updates, document generation, and more.

Creating a Webhook

You can create webhooks via the API or dashboard:

Via API

POST https://api.heydeo.ai/v1/webhooks

{
  "url": "https://your-domain.com/webhook",
  "events": [
    "shipment.created",
    "shipment.updated",
    "document.generated",
    "buyer.matched"
  ],
  "description": "Production webhook for shipment updates",
  "enabled": true
}

Response

{
  "id": "wh_1234567890",
  "url": "https://your-domain.com/webhook",
  "events": ["shipment.created", "shipment.updated", "document.generated", "buyer.matched"],
  "description": "Production webhook for shipment updates",
  "enabled": true,
  "secret": "whsec_abc123xyz789",
  "created_at": "2024-12-02T10:30:00Z"
}

Available Events

EventDescription
shipment.createdNew shipment record created
shipment.updatedShipment details updated
shipment.deletedShipment record deleted
document.generatedDocument successfully generated
document.failedDocument generation failed
buyer.matchedNew buyer match found
tariff.updatedTariff rates changed
hs_code.classifiedProduct HS code classified

Webhook Payload

All webhook requests include the following structure:

{
  "id": "evt_1234567890",
  "type": "shipment.created",
  "created_at": "2024-12-02T10:30:00Z",
  "data": {
    "object": {
      // Event-specific data
      "id": "ship_abc123",
      "origin_country": "US",
      "destination_country": "CN",
      "hs_code": "8517",
      "status": "pending",
      "created_at": "2024-12-02T10:30:00Z"
    }
  }
}

Verifying Webhook Signatures

Every webhook includes a signature in the X-Heydeo-Signature header. Verify this signature to ensure the request came from Heydeo:

Node.js Example

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const hmac = crypto.createHmac('sha256', secret);
  const digest = hmac.update(payload).digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(digest)
  );
}

// Express.js example
app.post('/webhook', (req, res) => {
  const signature = req.headers['x-heydeo-signature'];
  const payload = JSON.stringify(req.body);
  
  if (!verifyWebhook(payload, signature, process.env.WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }
  
  // Process the webhook
  console.log('Event:', req.body.type);
  res.sendStatus(200);
});

Python Example

import hmac
import hashlib

def verify_webhook(payload: str, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(),
        payload.encode(),
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(signature, expected)

# Flask example
@app.route('/webhook', methods=['POST'])
def webhook():
    signature = request.headers.get('X-Heydeo-Signature')
    payload = request.get_data(as_text=True)
    
    if not verify_webhook(payload, signature, os.getenv('WEBHOOK_SECRET')):
        return 'Invalid signature', 401
    
    event = request.json
    print(f"Event: {event['type']}")
    return '', 200

Responding to Webhooks

✅ Do: Return a 200 status code quickly (within 5 seconds)

✅ Do: Process webhooks asynchronously using a queue

❌ Don't: Perform long-running operations before responding

❌ Don't: Make API calls back to Heydeo before responding

Retry Logic

If your endpoint doesn't respond with a 200 status code, Heydeo will retry the webhook:

  • Retry 1: After 5 minutes
  • Retry 2: After 30 minutes
  • Retry 3: After 2 hours
  • Retry 4: After 6 hours
  • Retry 5: After 24 hours

After 5 failed attempts, the webhook will be marked as failed and no further retries will occur.

Testing Webhooks

Use the test endpoint to send sample webhook events:

POST https://api.heydeo.ai/v1/webhooks/wh_1234567890/test

{
  "event": "shipment.created"
}

Best Practices

  • 🔒 Always verify signatures - Protect against unauthorized requests
  • ⚡ Respond quickly - Return 200 immediately, process asynchronously
  • 🔄 Handle duplicates - Use event IDs to deduplicate webhook events
  • 📝 Log all webhooks - Keep records for debugging and auditing
  • 🛡️ Use HTTPS - Only HTTPS endpoints are supported for security
  • 🧪 Test thoroughly - Use test mode webhooks before going live

Managing Webhooks

List All Webhooks

GET https://api.heydeo.ai/v1/webhooks

Get Webhook Details

GET https://api.heydeo.ai/v1/webhooks/wh_1234567890

Update Webhook

PATCH https://api.heydeo.ai/v1/webhooks/wh_1234567890

{
  "enabled": false,
  "events": ["shipment.created"]
}

Delete Webhook

DELETE https://api.heydeo.ai/v1/webhooks/wh_1234567890