Skip to main content
PUT

Overview

The Update Webhook endpoint allows you to modify an existing webhook’s URL, actions, or status. Use this to change where notifications are sent, adjust which events you receive, or temporarily disable a webhook during maintenance.

Endpoint

Authentication

This endpoint requires HTTP Basic Authentication using your Secret Key.

Request

Path Parameters

string
required
The unique identifier of the webhook to update. You can get this ID from the Get Webhooks API or from the response when you created the webhook.Example: "a78efd32-de3b-4854-b599-11ae9f98f97e"

Headers

Prerequisites

Before updating a webhook, ensure you have:
  • Your Secret Key for HTTP Basic Authentication
  • The webhook ID of the webhook you want to update
See the Encryption Guide to understand how JWE tokens work — you’ll need this to decrypt incoming webhook notifications, not for the Update Webhook API request itself.

Body Parameters (Encrypted Payload)

The following parameters describe the payload that must be JWE-encrypted into the Token field. See the Encryption Guide for details on creating JWE tokens.
All body parameters are optional. Include only the fields you want to update. Fields you don’t include will remain unchanged.
The new HTTPS URL where Modulus Labs sends webhook notifications. Must be publicly accessible and use HTTPS.
  • Format: Valid HTTPS URL
  • Example: "https://api.yourcompany.com/webhooks/success"
New webhook status:
  • ENABLED - Webhook receives notifications
  • DISABLED - Webhook stops receiving notifications (useful during maintenance)
Example: "DISABLED"
Use DISABLED during server maintenance instead of deleting the webhook. This preserves your configuration and makes it easy to resume.

Example Payloads (Before Encryption)

Response

Success Response

Status Code: 200 OK Returns the updated webhook object with all current values.
string
Unique identifier for the webhook (unchanged).Example: "a78efd32-de3b-4854-b599-11ae9f98f97e"
string
String of webhook actions (updated or unchanged).Example: "QRPH_SUCCESS"
string
Current webhook status (updated or unchanged).Example: "DISABLED"
string
The webhook URL (updated or unchanged).Example: "https://api.yourcompany.com/webhooks/success"

Response Example

Error Responses

Status Code: 400Causes:
  • Invalid webhook URL format
  • Empty actions array
  • Invalid action values
  • Invalid status value
Response Example:
Solutions:
  • Ensure callbackUrl uses HTTPS protocol
  • Include at least one valid action if updating actions
  • Verify status is either ENABLED or DISABLED
Status Code: 401Cause: Invalid or missing authentication credentialsSolution:
  • Verify your secret key is correct
  • Ensure Authorization header format: Basic {base64(secret_key:)}
Status Code: 404Cause: Webhook ID does not existResponse Example:
Solutions:
  • Verify the webhook ID is correct
  • Use Get Webhooks API to find valid webhook IDs
  • Check if the webhook was deleted
Status Code: 409Cause: New webhook URL already registered for this merchantResponse Example:
Solution:
  • Use a different webhook URL, or
  • Delete the existing webhook using that URL first
Status Code: 500Cause: Unexpected server errorSolution:
  • Retry the request
  • If the issue persists, contact Modulus Labs support

Use Cases

Disable webhooks before server maintenance, enable after completion:
Update webhook URL when changing domains or infrastructure:
Change which events you want to receive:
Update webhook URL to use a new API version:
Create disabled webhook for testing, enable when ready:

Best Practices

Verify Before Updating

Check current webhook configuration before updating:

Test New URL First

Verify new webhook URL is accessible before updating:

Log All Changes

Track webhook configuration changes for audit purposes:

Graceful Status Changes

Notify your team before disabling production webhooks:

Partial Updates

You only need to include fields you want to change:

Troubleshooting

Symptom: Receive 404 error when updatingPossible Causes:
  • Wrong webhook ID
  • Webhook was deleted
  • Using wrong secret key (different merchant account)
Solutions:
  • Call Get Webhooks API to find valid webhook IDs
  • Verify you’re using the correct secret key
  • Check if webhook was deleted
Symptom: Receive 409 error when changing webhook URLCause: New URL is already registered for another webhookSolutions:
  • Use a different URL
  • Delete the other webhook using that URL first
  • Keep the current URL
Symptom: Webhook still receives old events or uses old URLPossible Causes:
  • Update request failed silently
  • Caching issue
  • Looking at wrong webhook
Solutions:
  • Verify update succeeded by checking response
  • Call Get Webhooks API to confirm changes
  • Clear any application caches

Next Steps

Delete Webhook

Permanently remove a webhook endpoint

Get Webhooks

View all registered webhooks

Test Webhook

Simulate webhooks to test your integration

Webhooks Overview

Learn about the Webhook API

Authorizations

Authorization
string
header
required

HTTP Basic Authentication using your Secret Key as the username and an empty password

Path Parameters

id
string
required

The unique identifier of the webhook

Body

application/json
request
object
required

Response

Webhook updated successfully

id
string

Unique identifier for the webhook

webhookAction
enum<string>[]

List of transaction events this webhook receives

Available options:
QRPH_SUCCESS,
QRPH_DECLINED
webhookStatus
enum<string>

Current status of the webhook

Available options:
ENABLED,
DISABLED
webhookUrl
string<uri>

The HTTPS URL where notifications are sent