Upgraded docs version is here ✨

Your documentation experience is getting an upgrade. Check it out now!

Go To Beta

Docs upgrade is here. Check it out!

Go To Beta
API ReferenceIntegrationsKnowledge Base

Webhook APIs

You can use the Webhooks APIs to receive event notifications or subscribe to events happening in a sub-merchant's account for the integration installed.

You can create, fetch, update and delete webhooks using these APIs.

Know more about Webhook Events and check the sample payloads for Sub-Merchant Onboarding Events.

You can try out our APIs on the Razorpay Postman Public Workspace.

Run in Postman

Webhook Entity🔗

The Webhook entity consists of the following fields. You can find the JSON sample entity on the right side.

wk_id
string The unique identifier of the created webhook. For example, HK890egfiItP3H. This id is used to fetch, update or delete a webhook. The maximum length is 14 characters.
created_at optional
integer The Unix timestamp at which the webhook has been created.
updated_at optional
integer The Unix timestamp at which the webhook has been updated.
owner_id mandatory
string The unique identifier generated by Razorpay for the sub-merchant who will receive the webhooks. For example, in this case, it will be account_id passed in the API URL.
owner_type mandatory
string Indicates the type of owner. For example, in this case, it will be the merchant.
url
string The URL where you receive the webhook payload when an event is triggered. The maximum length is 255 characters.
secret
string A secret for the webhook endpoint used to validate that the webhook is from Razorpay. If
alert_email
string This is the email address to which notifications must be sent in case of webhook failure.
secret_exists mandatory
boolean This attribute is set to true if a secret password has been set for the webhook endpoint. If no secret is sent in the request, this parameter does not appear in the response code.
entity mandatory
string Indicates the type of entity. For example, in this case, it will be webhook.
active optional
string Indicates the status of webhook.
  • true: Webhook in an activated state.
  • false: Webhook in a deactivated state.
events
object The required events from the list of Active Events. For example, payment.authorized, payment.captured, payment.failed, payment.dispute.created, refund.failed, refund.created and so on.

Create a Webhook🔗

Use the following API endpoint to create a webhook:

/accounts/:account_id/webhooks

Handy Tips
You can create up to 30 webhooks for an account_id.

Path Parameter🔗

account_id mandatory
string The unique identifier of the sub-merchant account generated by Razorpay for which a webhook is created. For example, acc_H3kYHQ635sBwXG. This id is used to fetch, update and delete a webhook. The webhook is created for this sub-merchant account id.

Request Parameters🔗

webhook_url mandatory
string The URL where you receive the webhook payload when an event is triggered. The maximum length is 255 characters.
alert_email optional
string This is the email address to which notifications must be sent in case of webhook failure.
secret optional
string A secret for the webhook endpoint that is used to validate that the webhook is from Razorpay.
events mandatory
object The required events from the list of Active Events. For example, payment.authorized, payment.captured, payment.failed, payment.dispute.created, refund.failed, refund.created and so on.

Response Parameters🔗

wk_id mandatory
string The unique identifier of the webhook generated by Razorpay. For example, HK890egfiItP3H.
created_at optional
integer The Unix timestamp at which the webhook has been created.
updated_at optional
integer The Unix timestamp at which the webhook has been updated.
owner_id mandatory
string The unique identifier generated by Razorpay for the sub-merchant who will receive the webhooks. For example, in this case, it will be account_id passed in the API URL.
owner_type mandatory
string Indicates the type of owner. For example, in this case, it will be the merchant.
webhook_url mandatory
string The URL where you receive the webhook payload when an event is triggered. The maximum length is 255 characters.
alert_email optional
string This is the email address to which notifications must be sent in case of webhook failure.
secret_exists mandatory
boolean This attribute will be set to true if a secret password has been set for the webhook endpoint.
entity mandatory
string Indicates the type of entity. For example, in this case, it will be webhook.
active optional
string Indicates the status of webhook.
  • true: Webhook in an activated state.
  • false: Webhook in a deactivated state.

Fetch a Webhook🔗

Use the following endpoint to retrieve and view the details of a webhook:

/accounts/:account_id/webhooks/:webhook_id

Path Parameters🔗

account_id mandatory
string The unique identifier of a sub-merchant account generated by Razorpay for which a webhook is created. For example, acc_H3kYHQ635sBwXG.
webhook_id mandatory
string The unique identifier of the webhook whose details are to be retrieved. For example, HK890egfiItP3H.

Fetch all Webhooks🔗

Use the following endpoint to retrieve all webhooks for a given account:

/accounts/:account_id/webhooks

Path Parameter🔗

account_id mandatory
string The unique identifier of a sub-merchant account generated by Razorpay for which a webhook is created. For example, acc_H3kYHQ635sBwXG.

Query Parameters🔗

from
integer Timestamp, in seconds, from when the webhooks are to be fetched.
to
integer Timestamp, in seconds, till when the webhooks are to be fetched.
count
integer Number of webhooks to be fetched. The default value is 10 and the maximum value is 100. This can be used for pagination, in combination with skip.
skip
integer Number of records to be skipped while fetching the webhooks. This can be used for pagination, in combination with count.

Update a Webhook🔗

Use the following endpoint to update the details of a webhook:

/accounts/:account_id/webhooks/:webhook_id

Path Parameters🔗

account_id mandatory
string The unique identifier of a sub-merchant account generated by Razorpay. For example, acc_H3kYHQ635sBwXG
webhook_id mandatory
string The unique identifier of the webhook whose details are to be updated. For example, HK890egfiItP3H

Delete a Webhook🔗

Use the following endpoint to delete the webhook of a sub-merchant's account generated by Razorpay:

/accounts/:account_id/webhooks/:webhook_id

Path Parameters🔗

account_id mandatory
string The unique identifier of a sub-merchant account generated by Razorpay. For example, acc_H3kYHQ635sBwXG.
webhook_id mandatory
string The unique identifier of the webhook whose details are to be deleted. For example, HK890egfiItP3H
×