Webhooks

Webhooks allow your application to receive real-time HTTP callbacks when events occur on the stemp platform.

Setup

1. Navigate to your application settings in the Developer Portal.
2. Add a webhook endpoint URL (must be HTTPS).
3. Select the events you want to subscribe to.
4. Save and note the signing secret.

Event Delivery

When an event occurs, stemp sends a POST request to your endpoint:

{
  "id": "evt_abc123",
  "type": "stamp.created",
  "timestamp": "2025-01-15T10:30:00Z",
  "data": {
    // Event-specific payload
  }
}

Headers

Signature Verification

Verify webhook authenticity by checking the signature:

import { createHmac } from 'crypto'

function verifyWebhook(payload: string, signature: string, secret: string): boolean {
  const expected = createHmac('sha256', secret)
    .update(payload)
    .digest('hex')
  return `sha256=${expected}` === signature
}

Always verify signatures before processing webhook payloads.

Retry Logic

If your endpoint returns a non-2xx status code, stemp retries delivery:

After 5 failed attempts, the delivery is marked as failed.

Best Practices

• Return a 200 response quickly; process events asynchronously.
• Use the delivery ID to deduplicate events.
• Always verify the webhook signature.
• Handle events idempotently — you may receive the same event more than once.