Delete Webhook Secret

DELETEhttps://api.omise.co/webhooks/secrets/:id

Delete a webhook signing secret from your account. This action is irreversible. Ensure you have created and deployed a replacement secret before deleting the current one, or webhook signature verification will fail.

---

Request Parameters

Required - 1 fieldRequired Parameters

▼

`id`STRING(required)

Webhook secret ID to delete (must be a valid webhook secret ID starting with whsec_).

Example:"whsec_test_5xuy4w91xqz7d1w9u0t"

Constraints:Must be a valid webhook secret ID

---

Responses

200

Webhook secret deleted successfully

Webhook secret permanently deleted. Webhooks can no longer be verified using this secret.

Deletion effects:

• The secret is permanently removed and cannot be recovered
• Webhook signatures created with this secret can no longer be verified
• If this was your only secret, webhook verification will fail until you create a new one
• Ensure your application is configured with a replacement secret before deletion

400

Bad request

Invalid webhook secret ID format.

Common causes:

• Webhook secret ID format is invalid
• ID does not start with whsec_

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

404

Not found

Webhook secret not found.

Common causes:

• Webhook secret ID does not exist
• Webhook secret has already been deleted
• Secret belongs to a different account

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/whsec_test_5xuy4w91xqz7d1w9u0t \
  -X DELETE \
  -u skey_test_5xuy4w91xqz7d1w9u0t:

Ruby

require 'omise'

Omise.api_key = 'skey_test_5xuy4w91xqz7d1w9u0t'

secret = Omise::WebhookSecret.destroy('whsec_test_5xuy4w91xqz7d1w9u0t')

Python

import omise

omise.api_secret = 'skey_test_5xuy4w91xqz7d1w9u0t'

secret = omise.WebhookSecret.retrieve('whsec_test_5xuy4w91xqz7d1w9u0t')
secret.destroy()

Node.js

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

const secret = await omise.webhookSecrets.destroy('whsec_test_5xuy4w91xqz7d1w9u0t');

PHP

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

$secret = OmiseWebhookSecret::retrieve('whsec_test_5xuy4w91xqz7d1w9u0t');
$secret->destroy();

Java

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

WebhookSecret secret = client.webhookSecrets().destroy("whsec_test_5xuy4w91xqz7d1w9u0t");

C#

var client = new Client("skey_test_5xuy4w91xqz7d1w9u0t");

var secret = await client.WebhookSecrets.Destroy("whsec_test_5xuy4w91xqz7d1w9u0t");

Go

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

deleted, _ := client.WebhookSecrets().Destroy("whsec_test_5xuy4w91xqz7d1w9u0t")

---

Error and result codes

Common Error Codes

Code	Description	Resolution
bad_request	Invalid webhook secret ID format	Check ID format starts with whsec_
authentication_failure	Invalid API key	Verify your secret key is correct
not_found	Webhook secret not found	Verify webhook secret ID exists

Deletion Response

Field	Description
object	Object type (always "webhook_secret")
id	ID of the deleted webhook secret
deleted	Boolean flag (always true for successful deletions)
livemode	Whether this was a live mode secret

---

Important Notes

Key Rotation Best Practices

When rotating webhook secrets, follow these steps to avoid verification failures:

1. Create a new secret using the Create Webhook Secret endpoint
2. Update your application to verify webhooks using both the old and new secrets
3. Deploy the changes to your production environment
4. Wait for confirmation that the new secret is working correctly
5. Delete the old secret using this endpoint

Avoiding Downtime

If you delete your only active webhook secret:

• Incoming webhooks will fail signature verification
• Your application will not be able to verify webhook authenticity
• You should temporarily accept unverified webhooks or queue them for later verification

Always ensure you have a replacement secret deployed before deleting an active secret.

---

🔑API Credentials

▼

Try it out

Required - 1 fields

▼

id(Required)

Your IP: ...Loading...