Prompteus
Sign inSign up

Webhooks

Receive real-time notifications when events happen in your Prompteus account

Overview

Webhooks allow you to receive real-time HTTP notifications when specific events occur in your Prompteus account. Instead of polling our API, you can subscribe to events and we'll push data to your endpoint as they happen.

Real-time

Instant notifications

Secure

HMAC-SHA256 signatures

Reliable

Automatic retries

Quick Start

Set up your first webhook in 3 steps

1

Create a webhook endpoint

Set up an HTTP endpoint on your server that can receive POST requests

2

Register the webhook

Add your endpoint URL in the Prompteus dashboard

3

Handle events

Process incoming webhook events in your application

Event Types

All available webhook events you can subscribe to

Products

product.created
A new product was created
product.updated
Product details were updated
product.published
Product was published to marketplace
product.deleted
Product was deleted

Orders

order.created
New order was placed
order.completed
Payment was successful
order.refunded
Order was refunded
order.failed
Payment failed

Workflows

workflow.started
Workflow execution started
workflow.completed
Workflow completed successfully
workflow.failed
Workflow execution failed
workflow.step.completed
Individual step completed

Subscriptions

subscription.created
New subscription started
subscription.updated
Subscription plan changed
subscription.cancelled
Subscription was cancelled
subscription.renewed
Subscription renewed

Payload Structure

Standard format for all webhook payloads

{
  "id": "evt_1234567890",
  "type": "order.completed",
  "created": "2024-01-15T10:30:00Z",
  "data": {
    "object": {
      "id": "ord_abc123",
      "product_id": "prod_xyz789",
      "buyer_id": "user_123",
      "amount": 29.99,
      "currency": "USD",
      "status": "completed",
      "created_at": "2024-01-15T10:29:00Z"
    }
  }
}
id
Unique event identifier
type
Event type (e.g., order.completed)
created
ISO 8601 timestamp
data
Event-specific data object

Security & Verification

Verify webhook authenticity with signature validation

const crypto = require('crypto');

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

// In your webhook handler
app.post('/webhooks/prompteus', (req, res) => {
  const signature = req.headers['x-prompteus-signature'];
  const payload = JSON.stringify(req.body);
  
  if (!verifyWebhookSignature(payload, signature, WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }
  
  // Process the webhook
  const event = req.body;
  console.log('Received event:', event.type);
  
  res.status(200).send('OK');
});

Retry Policy

Automatic retry behavior for failed webhook deliveries

// Webhook retry schedule
1st retry: 5 seconds
2nd retry: 30 seconds
3rd retry: 2 minutes
4th retry: 10 minutes
5th retry: 30 minutes
6th retry: 2 hours
7th retry: 6 hours
8th retry: 24 hours

// After 8 failed attempts, the webhook is marked as failed
// and no further retries are attempted

Best Practices

  • Return a 2xx status code quickly (within 5 seconds)
  • Process webhooks asynchronously when possible
  • Implement idempotency to handle duplicate events
  • Store the event ID to prevent reprocessing

Testing Webhooks

Test Mode

Use test mode to send sample events to your endpoint

Local Development

Use ngrok or similar tools to expose your local server

ngrok http 3000

Webhook Logs

View delivery attempts and responses in your dashboard

Sample Payloads

Download sample payloads for all event types

Webhook CLI

Test webhooks locally with our CLI tool