Create Webhook Secret

POSThttps://api.omise.co/webhooks/secrets

Create a new webhook signing secret for your account. The secret value is only returned once at creation time - store it securely immediately. Use this secret to verify that incoming webhook events are genuinely from Omise.

---

Request Parameters

This endpoint does not require any request parameters. A new signing secret will be generated automatically.

Optional - 1 fieldOptional Parameters

▼

---

Responses

200

Webhook secret created successfully

Webhook secret created. The secret value is included in this response only - it will not be retrievable again. Store it securely immediately.

Response includes:

• object - Object type (always "webhook_secret")
• id - Unique secret identifier (whsec_*). Store this for management.
• secret - The actual signing secret. Store this immediately - it will not be shown again.
• livemode - Whether this is a live mode secret
• created_at - ISO 8601 timestamp of creation
• metadata - Custom key-value data (if provided)

400

Bad request

Request validation failed. Check the error message for details.

Common causes:

• Metadata exceeds 15,000 characters
• Invalid metadata format
• Maximum number of secrets reached

401

Unauthorized

Authentication failed. Invalid or missing API key.

Common causes:

• Missing Authorization header
• Invalid secret key
• Using public key instead of secret key
• Incorrect HTTP Basic Auth format

5xx

Server error

Server-side error occurred. These are rare but should be handled gracefully.

How to handle:

• Retry the request with exponential backoff
• Check status.omise.co for service incidents
• See Error Handling for detailed guidance

---

Code samples

cURL

curl https://api.omise.co/webhooks/secrets \
  -u skey_test_5xuy4w91xqz7d1w9u0t: \
  -X POST

Ruby

require 'omise'

Omise.api_key = 'skey_test_5xuy4w91xqz7d1w9u0t'

secret = Omise::WebhookSecret.create({
  metadata: {
    environment: 'production'
  }
})

# Store secret.secret securely - it won't be shown again
puts secret.secret

Python

import omise

omise.api_secret = 'skey_test_5xuy4w91xqz7d1w9u0t'

secret = omise.WebhookSecret.create(
    metadata={
        'environment': 'production'
    }
)

# Store secret.secret securely - it won't be shown again
print(secret.secret)

Node.js

const omise = require('omise')({
  secretKey: 'skey_test_5xuy4w91xqz7d1w9u0t'
});

const secret = await omise.webhookSecrets.create({
  metadata: {
    environment: 'production'
  }
});

// Store secret.secret securely - it won't be shown again
console.log(secret.secret);

PHP

<?php
define('OMISE_SECRET_KEY', 'skey_test_5xuy4w91xqz7d1w9u0t');

$secret = OmiseWebhookSecret::create([
    'metadata' => [
        'environment' => 'production'
    ]
]);

// Store $secret['secret'] securely - it won't be shown again
echo $secret['secret'];

Java

Client client = new Client.Builder()
    .secretKey("skey_test_5xuy4w91xqz7d1w9u0t")
    .build();

WebhookSecret secret = client.webhookSecrets().create()
    .metadata("environment", "production")
    .send();

// Store secret.getSecret() securely - it won't be shown again
System.out.println(secret.getSecret());

C#

var client = new Client("skey_test_5xuy4w91xqz7d1w9u0t");

var secret = await client.WebhookSecrets.Create(new CreateWebhookSecretRequest
{
    Metadata = new Dictionary<string, string>
    {
        { "environment", "production" }
    }
});

// Store secret.Secret securely - it won't be shown again
Console.WriteLine(secret.Secret);

Go

client, _ := omise.NewClient(
    "pkey_test_5xuy4w91xqz7d1w9u0t",
    "skey_test_5xuy4w91xqz7d1w9u0t",
)

secret, _ := client.WebhookSecrets().Create(&operations.CreateWebhookSecret{
    Metadata: map[string]string{
        "environment": "production",
    },
})

// Store secret.Secret securely - it won't be shown again
fmt.Println(secret.Secret)

---

Error and result codes

Common Error Codes

Code	Description	Resolution
authentication_failure	Invalid API key	Verify your secret key is correct
bad_request	Invalid parameters	Check metadata format and size
limit_reached	Maximum secrets reached	Delete unused secrets before creating new ones

Webhook Secret Fields

Field	Description
object	Object type (always "webhook_secret")
id	Unique secret identifier (whsec_*)
secret	The signing secret (only shown at creation)
livemode	Whether this is a live mode secret
created_at	ISO 8601 timestamp of creation
metadata	Custom key-value data

---

Important Notes

Store the Secret Immediately

The secret field is only returned once when the webhook secret is created. After this response, you will only be able to see the secret's ID, creation date, and metadata - not the actual secret value.

Store the secret in a secure location such as:

• Environment variables
• AWS Secrets Manager
• HashiCorp Vault
• Google Cloud Secret Manager
• Azure Key Vault

Using Multiple Secrets

You can have multiple active webhook secrets at once. This is useful during key rotation:

1. Create a new secret
2. Update your verification code to accept both old and new secrets
3. Deploy the updated verification code
4. Delete the old secret

---

🔑API Credentials

▼

Try it out

Additional - 1 fields

▼

Your IP: ...Loading...