Skip to main content

​
Webhooks

Webhooks let you subscribe to events from your LLMTune workspace for automation and monitoring. Receive real-time notifications when training jobs complete, deployments change, or usage thresholds are reached.

​
Supported Events

EventTrigger
training.startedA fine-tuning job enters the running state
training.completedA job finishes successfully
training.failedA job fails or is cancelled
model.deployedA model is promoted to an endpoint
deployment.createdA new endpoint becomes active
deployment.pausedAn endpoint is paused
deployment.deletedAn endpoint is permanently removed
usage.threshold_reachedUsage metrics cross configured thresholds

​
Register a Webhook

  1. Navigate to Webhooks in the dashboard.
  2. Click Create Webhook.
  3. Provide:
    • Target URL (HTTPS recommended)
    • Secret for signature validation (optional but recommended)
    • Events to subscribe to (select one or more)
  4. Save and test using the Send Test Event button.

​
Payload Format

LLMTune sends POST requests to your webhook URL with the following payload structure: 
{
  "event": "training.completed",
  "data": {
    "jobId": "job-uuid",
    "baseModel": "meta-llama/Llama-3.3-70B-Instruct",
    "artifact": "ionet-finetune-model-id",
    "metrics": {
      "loss": 1.12,
      "tokens": 3250000,
      "duration_seconds": 1450
    }
  },
  "deliveredAt": "2025-11-08T14:22:31Z"
}

​
Training Events

{
  "event": "training.completed",
  "data": {
    "jobId": "job-uuid",
    "baseModel": "meta-llama/Llama-3.3-70B-Instruct",
    "trainingMethod": "sft",
    "status": "completed",
    "metrics": {
      "loss": 1.12,
      "evalLoss": 1.02,
      "tokensPerSecond": 178,
      "totalTokens": 3250000
    },
    "createdAt": "2025-11-01T15:23:54Z",
    "completedAt": "2025-11-01T16:45:12Z"
  }
}

​
Deployment Events

{
  "event": "model.deployed",
  "data": {
    "deploymentId": "deploy-uuid",
    "modelId": "meta-llama/Llama-3.3-70B-Instruct",
    "version": "v1",
    "environment": "production",
    "endpoint": "https://api.llmtune.io/v1/models/deploy-uuid/inference"
  }
}

​
Signature Verification

LLMTune signs webhook payloads using HMAC SHA-256. Verify signatures using your shared secret: 
const crypto = require('crypto');

function verifySignature(payload, signature, secret) {
  const hmac = crypto.createHmac('sha256', secret);
  const digest = hmac.update(JSON.stringify(payload)).digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(digest)
  );
}
The signature is included in the X-LLMTune-Signature header.

​
Response Handling

  • Respond with 2xx status codes to acknowledge receipt
  • LLMTune retries failed deliveries with exponential backoff
  • Maximum retry attempts: 5
  • Timeout: 30 seconds per request

​
Best Practices

  1. Use unique secrets per webhook endpoint
  2. Acknowledge quickly – Respond with 200 OK immediately, then process asynchronously
  3. Log received events for debugging and auditing
  4. Validate signatures to ensure requests are from LLMTune
  5. Handle idempotency – Events may be delivered multiple times; use event IDs to deduplicate
  6. Monitor webhook health – Set up alerts if webhooks fail repeatedly

​
Testing Webhooks

  1. Use the Send Test Event button in the webhook configuration
  2. Test your endpoint locally using tools like ngrok or localtunnel
  3. Verify your endpoint handles all subscribed event types

​
Troubleshooting

  • Webhook not receiving events: Check that your endpoint is publicly accessible (HTTPS) and returns 2xx responses
  • Signature verification fails: Ensure you’re using the correct secret and computing the signature correctly
  • Events delayed: Check your endpoint response time; slow responses may cause retries
  • Missing events: Review webhook logs in the dashboard to see delivery status

​
Next Steps