Webhook Forwarding

Webhook forwarding allows you to relay Tape notifications to other systems or services that support webhook endpoints. This is useful for integrating with custom applications, third-party services, or internal tools.

How Webhook Forwarding Works

When you set up webhook forwarding:

  1. Tape sends a notification to TapeAlert
  2. The hub processes and logs the notification
  3. The hub then forwards the notification to your specified endpoint
  4. If configured, the request includes an HMAC signature for security

Setting Up Webhook Forwarding

Step 1: Prepare Your Endpoint

First, ensure you have an endpoint ready to receive webhook data:

  1. Set up an HTTP endpoint that can accept POST requests
  2. Ensure your endpoint can handle JSON payloads
  3. (Optional) Implement signature verification if you plan to use HMAC signatures

Step 2: Add Webhook Forwarding as a Destination

Next, configure webhook forwarding in TapeAlert:

  1. Navigate to your webhook in TapeAlert
  2. Click Add Destination
  3. Select Webhook as the destination type
  4. Provide a name for this destination (e.g., “Internal API”)
  5. Enter the URL of your endpoint
  6. (Optional) Configure security options (see below)
  7. Click Save

Security Options

HMAC Signature Verification

You can secure your webhook with an HMAC signature:

  1. When adding the webhook destination, enable the Add Security Signature option
  2. Enter a secret key
  3. The hub will generate an HMAC-SHA256 signature for each request
  4. The signature is included in the X-Signature header
  5. A timestamp is included in the X-Signature-Timestamp header

Example code to verify the signature on your end:

// Example signature verification in Node.js
const crypto = require('crypto');

function verifySignature(payload, signature, timestamp, secret) {
  // Create a signature using the same method as TapeAlert
  const hmac = crypto.createHmac('sha256', secret);
  hmac.update(timestamp + '.' + payload);
  const expectedSignature = hmac.digest('hex');
  
  // Compare signatures using a constant-time comparison function
  return crypto.timingSafeEqual(
    Buffer.from(expectedSignature, 'hex'),
    Buffer.from(signature, 'hex')
  );
}

// How to use in an Express.js handler
app.post('/webhook', (req, res) => {
  const signature = req.headers['x-signature'];
  const timestamp = req.headers['x-signature-timestamp'];
  const payload = JSON.stringify(req.body);
  const secret = 'your-webhook-secret';
  
  if (!verifySignature(payload, signature, timestamp, secret)) {
    return res.status(401).send('Invalid signature');
  }
  
  // Process the webhook
  console.log('Webhook verified:', req.body);
  res.status(200).send('OK');
});

Webhook Payload Format

The webhook payload includes:

{
  "source": "tape-notifications-hub",
  "timestamp": 1749141772975,
  "webhook_id": "5a2880ec-3628-406d-8b5f-f8f00dc93b15",
  "organization_id": "453aecbd-392e-4030-8228-3a0635de1a63",
  "data": {
    "hook_id": 111531,
    "type": "run.failed",
    "app_id": 60657,
    "organization_id": 1703,
    "organization_name": "Melotte Consulting-Demos",
    "organization_slug": "melotteconsulting-demo",
    "workflow_def_id": 301057,
    "workflow_def_name": "error",
    "workflow_def_broken": false,
    "workflow_def_url": "https://tapeapp.com/melotteconsulting-demo/(home//root-modal:workflow-center/edit-workflow/301057)",
    "workflow_run_id": 24484218,
    "error_message": "EXIT_ON_PURPOSE",
    "triggered_on_record_id": 154205271,
    "triggered_on_record_url": "https://tapeapp.com/melotteconsulting-demo/(home//main-modal:record/154205271)"
  }
}

The data field contains the original notification from Tape, which varies depending on the notification type (workflow error, usage notification, etc.).

Testing Your Webhook

After setting up webhook forwarding, you should test it:

  1. From your destination settings, click the Test button
  2. A test notification will be sent to your endpoint
  3. Verify that the notification was received correctly
  4. If using signatures, verify that the signature validation works

Troubleshooting

Common Issues

  • Timeouts: Webhooks will timeout after 10 seconds
  • Connection Errors: Make sure your endpoint is accessible over the internet
  • Status Codes: Your endpoint should return a 2xx status code to indicate success
  • Signature Mismatch: Ensure the secret key exactly matches on both ends

Verifying Webhook Receipt

You can check if your webhook was correctly sent:

  1. Navigate to the webhook’s notification logs in TapeAlert
  2. Find the relevant notification
  3. Check the delivery status for your webhook destination
  4. View any error messages that might have occurred during delivery

Best Practices

  • Idempotency: Design your webhook consumer to handle duplicate events
  • Asynchronous Processing: Process heavy work asynchronously after acknowledging receipt
  • Quick Response: Respond to webhook requests quickly to prevent timeouts
  • Error Handling: Implement robust error handling on your webhook endpoint
  • Security: Always use HMAC signatures when the webhook is public-facing
  • IP Allow Lists: Consider setting up IP allow lists for additional security

Next Steps