Create Webhook API

The Create Webhook API allows you to configure a webhook endpoint where PhonePe will send real-time event notifications for specific transaction and refund events. By registering your webhook URL along with authentication credentials and event preferences, you can receive timely callbacks and automate your post-payment or refund workflows.

Environment

Environment	Http Method	API
`Sandbox`	`POST`	https://api-preprod.phonepe.com/apis/pg-sandbox/configs/v1/webhooks
`Production`	`POST`	https://api.phonepe.com/apis/pg/configs/v1/webhooks

Request

Request Headers

Header Name	Header Value	Description
`Content-Type`	application/json
`Authorization`	O-Bearer <access_token>	Pass `access_token` received in Authorization call

Request Payload

{
    "url": "https://webhook.site/f9c9b854-72f1-462a-b28e-e3e9e4dee939",
    "description": "Webhook description",
    "username": "username",
    "password": "password123",
    "events": [
        "checkout.order.completed",
        "checkout.order.failed"
    ]
}

Field Name	Data Type	Description
`url`	String	The HTTPS webhook URL to which PhonePe have to post the webhook response.
`description`	String	Description of the Webhook URL
`username`	String	username length must be between 5 and 20. It should be alphanumeric only.
`password`	String	password must be 8-20 characters long. It should be alphanumeric and contain both letters and numbers.
`events`	Array	webhook events for which callback is required.

Events

Standard Checkout
- Payment Flow
  - checkout.order.completed
  - checkout.order.failed
- Refund Flow
  - pg.refund.completed
  - pg.refund.failed

Custom Checkout
- Payment Flow
  - pg.order.completed
  - pg.order.failed
- Refund Flow
  - pg.refund.completed
  - pg.refund.failed

Response

Response Headers

Header Name	Header Value
`Content-Type`	application/json

Sample Response for case 1: Success Response

{
    "id": "CF2410212252436169514926",
    "url": "https://webhook.site/f9c9b854-72f1-462a-b28e-e3e9e4dee939",
    "description": "Webhook description",
    "username": "username",
    "password": "password123",
    "events": [
        "pg.order.completed",
        "pg.order.failed"
    ],
    "createdAt": 1729531363628,
    "updatedAt": 1729531363632,
    "enabled": true
}

Sample Response for case 2: Failed with Invalid Auth Token

{
    "code": "BAD_REQUEST",
    "message": "Cannot make more than 30 webhooks"
}

Sample Response for case 3: Failed with Invalid Auth Token

{
    "code": "AUTHORIZATION_FAILED",
    "message": "Authorization failed [message = Please check the authorization token and try again]"
}

Sample Response case 4: Internal Server Error

{
    "code": "INTERNAL_SERVER_ERROR",
    "message": "There is an error trying to process your transaction at the moment. Please try again in a while."
}

Field Name	Data Type	Description
`id`	String	Unique identifier of the webhook. This ID can be used to update or delete the webhook.
`url`	String	The secure HTTPS endpoint where PhonePe will send webhook event notifications.
`description`	String	A brief description to identify the purpose or context of the webhook URL.
`username`	Long	Username must be 5 to 20 characters long and alphanumeric.
`password`	String	Password must be 8 to 20 characters long, alphanumeric, and include both letters and numbers.
`events`	Array	List of webhook events for which you want to receive callbacks.
`createdAt`	Long	Epoch timestamp indicating when the webhook was created.
`updatedAt`	Long	Epoch timestamp indicating the last time the webhook was updated.
`enabled`	Boolean	Flag to indicate whether the webhook is currently active or not.