Webhooks Secrets API

Interactive Webhook Tester

Explore webhook events, view example payloads, and test your endpoint:

Interactive Webhook Tester

Explore webhook events and test your endpoint

Select Event Typecharge.completecharge.createcharge.capturecharge.reversecharge.expirerefund.createcustomer.createcustomer.updatecustomer.destroycard.createcard.destroydispute.createdispute.closerecipient.createrecipient.activatetransfer.createtransfer.paytransfer.failschedule.createschedule.destroylink.createlink.complete

Triggered when a charge is completed successfully

POSTcharge.complete

{
  "object": "event",
  "id": "evnt_test_5h2m123lxlx4z7yh9a2",
  "livemode": false,
  "location": "/events/evnt_test_5h2m123lxlx4z7yh9a2",
  "webhook_deliveries": [],
  "data": {
    "object": "charge",
    "id": "chrg_test_5h2m123abc456def",
    "amount": 100000,
    "currency": "thb",
    "description": "Test charge",
    "status": "successful",
    "authorized": true,
    "paid": true,
    "captured": true,
    "capture": true,
    "refunded": 0,
    "reversed": false,
    "voided": false,
    "expired": false,
    "disputable": true,
    "capturable": false,
    "reversible": false,
    "transaction": "trxn_test_5h2m123abc456def",
    "source_of_fund": "card",
    "failure_code": null,
    "failure_message": null,
    "card": {
      "object": "card",
      "id": "card_test_5h2m123abc456def",
      "livemode": false,
      "brand": "Visa",
      "last_digits": "4242",
      "name": "Test User",
      "expiration_month": 12,
      "expiration_year": 2025,
      "fingerprint": "FpEYKqwFa3znwjpHlEHjHg==",
      "security_code_check": true
    },
    "created_at": "2026-03-09T09:54:52.108Z"
  },
  "key": "charge.complete",
  "created_at": "2026-03-09T09:54:52.112Z"
}

The Webhooks Secrets API allows you to manage signing secrets used to verify webhook authenticity. Each webhook event sent by Omise includes a signature that you can validate using your signing secret to ensure the event genuinely originated from Omise.

Overview

Webhook secrets provide:

• Event authenticity - Verify webhooks are from Omise, not attackers
• Tamper detection - Detect if webhook payloads have been modified
• Multiple secrets - Support key rotation without downtime
• Secure key management - Create, list, and delete secrets programmatically

How Webhook Signatures Work

1. Secret Creation - Create a signing secret via the API
2. Signature Generation - Omise signs each webhook using your secret
3. Signature Verification - Your server validates the signature before processing
4. Secret Rotation - Periodically rotate secrets for enhanced security

Webhook Signature Structure

Each webhook request includes signature headers:

• Omise-Signature - Hex-encoded HMAC-SHA256 signature (may contain two comma-separated signatures during secret rotation)
• Omise-Signature-Timestamp - Unix timestamp when the signature was generated

Verifying Webhook Signatures

To verify a webhook signature:

1. Extract the timestamp and signature from the headers
2. Concatenate the timestamp and raw request body
3. Compute HMAC-SHA256 using your signing secret
4. Compare the computed signature with the received signature
5. Verify the timestamp is recent (within 5 minutes) to prevent replay attacks

import hmac
import hashlib
import time

def verify_webhook(payload, signature, timestamp, secret):
    # Check timestamp is within 5 minutes
    current_time = int(time.time())
    if abs(current_time - int(timestamp)) > 300:
        return False

    # Compute expected signature
    message = f"{timestamp}.{payload}"
    expected_sig = hmac.new(
        secret.encode(),
        message.encode(),
        hashlib.sha256
    ).hexdigest()

    # Compare signatures securely
    return hmac.compare_digest(expected_sig, signature)

Secret Object Structure

Each webhook secret contains:

• Secret ID - Unique identifier (whsec_*)
• Secret Value - The signing key (shown only at creation)
• Created At - When the secret was created
• Livemode - Whether this is a live or test mode secret

Key Use Cases

Webhook Verification

Validate that incoming webhooks are genuinely from Omise before processing them.

Key Rotation

Create a new secret, update your verification code to accept both, then delete the old secret.

Security Compliance

Maintain audit trails of secret creation and deletion for compliance requirements.

Multi-Environment Setup

Use separate secrets for development, staging, and production environments.

Available Endpoints

• List Webhook Secrets - GET /webhooks/secrets
• Create Webhook Secret - POST /webhooks/secrets
• Delete Webhook Secret - DELETE /webhooks/secrets/:id

Best Practices

Do This

• Always verify signatures before processing webhooks
• Check timestamps to prevent replay attacks
• Rotate secrets periodically (every 90 days recommended)
• Support multiple secrets during rotation periods
• Store secrets securely in environment variables or secret managers
• Use constant-time comparison to prevent timing attacks

Don't Do This

• Don't log secrets in application logs
• Don't hardcode secrets in source code
• Don't skip verification even in development
• Don't ignore timestamp checks as they prevent replay attacks
• Don't share secrets across environments

Security Considerations

Secret Storage

• Store secrets in secure secret management systems (AWS Secrets Manager, HashiCorp Vault, etc.)
• Never commit secrets to version control
• Use environment variables for deployment

Key Rotation

• Create new secret before deleting old one
• Update verification code to check both secrets during transition
• Delete old secret only after confirming new secret works
• Aim to complete rotation within 24-48 hours

Replay Attack Prevention

• Always validate the timestamp header
• Reject webhooks with timestamps older than 5 minutes
• Consider implementing idempotency based on event IDs

Related Resources

• Webhooks Guide
• Events API
• Error Handling

---

Need help? Check our Webhooks Guide or contact support@omise.co