> ## Documentation Index
> Fetch the complete documentation index at: https://razorpay-881012b3.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a Webhook

> Create a webhook using Razorpay APIs to receive event notifications.

<div style={{display:"flex",flexWrap:"wrap",alignItems:"center",gap:"0.35rem 0.9rem",border:"1px solid rgba(128,128,128,0.28)",borderRadius:"0.5rem",padding:"0.45rem 0.75rem",margin:"0 0 1.25rem",fontSize:"0.875rem"}}>
  <span style={{fontWeight:600}}>Available in</span>
  <span>🇮🇳 India</span>
  <span>🇸🇬 Singapore</span>
  <span>🇺🇸 United States</span>
</div>

Use this API endpoint to create a webhook. Know about the [various error responses](/docs/api/partners/errors) for this API.

<Info>
  **Handy Tips**

  You can create up to 30 webhooks for an `account_id`.
</Info>

<RequestExample>
  ```bash Curl theme={null}
  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": "gaurav.kumar@example.com",
    "secret": "12345",
    "events": [
      "payment.authorized",
      "payment.failed",
      "payment.captured",
      "payment.dispute.created",
      "refund.failed",
      "refund.created"
    ]
  }'
  ```

  ```java Java theme={null}
  RazorpayClient razorpay = new RazorpayClient("[ACCESS_TOKEN]");

  String accountId = "acc_GP4lfNA0iIMn5B";

  JSONObject webhookRequest = new JSONObject();
  webhookRequest.put("url","https://google.com");
  webhookRequest.put("alert_email","gaurav.kumar@example.com");
  webhookRequest.put("secret","12345");

  ArrayList<String> events = new ArrayList<String>();
  events.add("payment.authorized");
  events.add("payment.failed");
  events.add("payment.captured");
  events.add("payment.dispute.created");
  events.add("refund.failed");
  events.add("refund.created");

  webhookRequest.put("events",events);

  Webhook webhook = instance.webhook.create(accountId, webhookRequest);
  ```

  ```ruby Ruby theme={null}
  require "razorpay"
  Razorpay.setup('ACCESS_TOKEN')
  accountId = "acc_GP4lfNA0iIMn5B"

  Razorpay::Webhook.create({
    "url": "https://google.com",
    "alert_email": "gaurav.kumar@example.com",
    "secret": "12345",
    "events": [
      "payment.authorized",
      "payment.failed",
      "payment.captured",
      "payment.dispute.created",
      "refund.failed",
      "refund.created"
    ]
  }, accountId)
  ```

  ```csharp .NET theme={null}
  RazorpayClient client = new RazorpayClient("[ACCESS_TOKEN]");

  String accountId = "acc_ua2tBezhcEBvap";

  Dictionary<string, object> webhookRequest = new Dictionary<string, object>();
  webhookRequest.Add("url", "https://www.google.com");
  webhookRequest.Add("alert_email", "gaurav.kumar@example.com");
  List<string> events = new List<string>();
  events.Add("refund.created");
  events.Add("payment.authorized");
  events.Add("payment.failed");
  events.Add("payment.captured");
  events.Add("payment.dispute.created");
  events.Add("refund.failed");
  events.Add("refund.created");
  webhookRequest.Add("secret", "12345");
  webhookRequest.Add("events", events);

  Webhook webhook = client.Webhook.Create(webhookRequest, accountId);
  ```
</RequestExample>

<ResponseExample>
  ```json Success theme={null}
  {
    "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": "gaurav.kumar@example.com",
    "secret_exists": true,
    "entity": "webhook",
    "active": true,
    "events": [
      "payment.authorized",
      "payment.failed",
      "payment.captured",
      "payment.dispute.created",
      "refund.failed",
      "refund.created"
    ]
  }
  ```
</ResponseExample>

## Path Parameters

<ParamField path="account_id" type="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.
</ParamField>

## Request Parameters

<ParamField body="url" type="string" required>
  The URL where you receive the webhook payload when an event is triggered. The maximum length is 255 characters.
</ParamField>

<ParamField body="alert_email" type="string">
  This is the email address to which notifications must be sent in case of webhook failure.
</ParamField>

<ParamField body="secret" type="string">
  A secret for the webhook endpoint that is used to validate that the webhook is from Razorpay.
</ParamField>

<ParamField body="events" type="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.
</ParamField>

## Response Parameters

<ResponseField name="id" type="string">
  The unique identifier of the webhook generated by Razorpay. For example, `HK890egfiItP3H`.
</ResponseField>

<ResponseField name="created_at" type="integer">
  The Unix timestamp at which the webhook has been created.
</ResponseField>

<ResponseField name="updated_at" type="integer">
  The Unix timestamp at which the webhook has been updated.
</ResponseField>

<ResponseField name="owner_id" type="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.
</ResponseField>

<ResponseField name="owner_type" type="string">
  Indicates the type of owner. For example, in this case, it will be the merchant.
</ResponseField>

<ResponseField name="url" type="string">
  The URL where you receive the webhook payload when an event is triggered. The maximum length is 255 characters.
</ResponseField>

<ResponseField name="secret" type="string">
  A secret for the webhook endpoint used to validate that the webhook is from Razorpay.
</ResponseField>

<ResponseField name="alert_email" type="string">
  This is the email address to which notifications must be sent in case of webhook failure.
</ResponseField>

<ResponseField name="secret_exists" type="boolean">
  This attribute will be set to `true` if a secret password has been set for the webhook endpoint.
</ResponseField>

<ResponseField name="entity" type="string">
  Indicates the type of entity. For example, in this case, it will be **webhook**.
</ResponseField>

<ResponseField name="active" type="string">
  Indicates the status of webhook.

  * `true`: Webhook in an activated state.
  * `false`: Webhook in a deactivated state.
</ResponseField>

<ResponseField name="events" type="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.
</ResponseField>