Create a Webhook

Create a webhook using Razorpay APIs to receive event notifications.

POST /v2/accounts/:account_id/webhooks

Curl

curl -X POST https://api.razorpay.com/v2/accounts/acc_JOGUdtKu3dB03d/webhooks \
-u <ACCESS_TOKEN> \
-H "Content-Type: application/json" \
-d '{
  "url": "https://google.com",
  "alert_email": "[e-mail]",
  "secret": "12345",
  "events": [
    "payment.authorized",
    "payment.failed",
    "payment.captured",
    "payment.dispute.created",
    "refund.failed",
    "refund.created"
  ]
}'

Success

{
  "id": "JebiXkKGYwua5L",
  "created_at": 1654605478,
  "updated_at": 1654605478,
  "service": "beta-api-live",
  "owner_id": "JOGUdtKu3dB03d",
  "owner_type": "merchant",
  "context": [],
  "disabled_at": 0,
  "url": "https://google.com",
  "alert_email": "[e-mail]",
  "secret_exists": true,
  "entity": "webhook",
  "active": true,
  "events": [
    "payment.authorized",
    "payment.failed",
    "payment.captured",
    "payment.dispute.created",
    "refund.failed",
    "refund.created"
  ]
}

Use this API endpoint to create a webhook. Know about the various error responses for this API.

Handy Tips

You can create up to 30 webhooks for an account_id.

Curl

curl -X POST https://api.razorpay.com/v2/accounts/acc_JOGUdtKu3dB03d/webhooks \
-u <ACCESS_TOKEN> \
-H "Content-Type: application/json" \
-d '{
  "url": "https://google.com",
  "alert_email": "[e-mail]",
  "secret": "12345",
  "events": [
    "payment.authorized",
    "payment.failed",
    "payment.captured",
    "payment.dispute.created",
    "refund.failed",
    "refund.created"
  ]
}'

Success

{
  "id": "JebiXkKGYwua5L",
  "created_at": 1654605478,
  "updated_at": 1654605478,
  "service": "beta-api-live",
  "owner_id": "JOGUdtKu3dB03d",
  "owner_type": "merchant",
  "context": [],
  "disabled_at": 0,
  "url": "https://google.com",
  "alert_email": "[e-mail]",
  "secret_exists": true,
  "entity": "webhook",
  "active": true,
  "events": [
    "payment.authorized",
    "payment.failed",
    "payment.captured",
    "payment.dispute.created",
    "refund.failed",
    "refund.created"
  ]
}

Path Parameters

account_id · string · required

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

url · string · required

The URL where you receive the webhook payload when an event is triggered. The maximum length is 255 characters.

alert_email · string

This is the email address to which notifications must be sent in case of webhook failure.

secret · string

A secret for the webhook endpoint that is used to validate that the webhook is from Razorpay.

events · object · required

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

id · string

The unique identifier of the webhook generated by Razorpay. For example, HK890egfiItP3H.

created_at · integer

The Unix timestamp at which the webhook has been created.

updated_at · integer

The Unix timestamp at which the webhook has been updated.

owner_id · 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 · 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.

alert_email · string

This is the email address to which notifications must be sent in case of webhook failure.

secret_exists · boolean

This attribute will be set to true if a secret password has been set for the webhook endpoint.

entity · string

Indicates the type of entity. For example, in this case, it will be webhook.

active · 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.