---
page_source: https://docs.juspay.io/payout-sea/docs/resources/webhooks
page_title: Webhooks
---


# Webhooks



After the completion of every order, Juspay will provide direct notification to your server regarding the event. These are called Webhooks. You must configure a valid HTTPS endpoint that is reachable from our servers to consume these notifications. Our servers will push data using HTTPS POST call to your endpoint.

Webhooks can be configured for order level, fulfillment level, and transaction level events from Juspay dashboard as per your requirement. Juspay can also provide webhooks for validation status of beneficiary created. 


#### **Events** 




| Event Name (value) | Event Type (label) | Description |
|---|---|---|
| FULFILLMENTS_SCHEDULED | ORDER | Fullfillment is added to the process tracker |
| FULFILLED_PARTIALLY | ORDER | One of the fulfillments is completed |
| FULFILLMENTS_FAILURE | ORDER | All fulfillment attempts have failed |
| FULFILLMENTS_SUCCESSFUL | ORDER | Fulfillment completed successfully |
| FULFILLMENTS_MANUAL_REVIEW | ORDER | One of the fulfillments is in manual review |
| FULFILLMENTS_CANCELLED | ORDER | Fulfillment cancelled by the merchant  |
| INITIATED | FULFILLMENT_ORDER | Fulfillment created at Juspay |
| FAILURE | FULFILLMENT_ORDER | Fulfillment failed |
| SUCCESS | FULFILLMENT_ORDER | Fulfillment completed successfully |
| DISCARDED | FULFILLMENT_ORDER | Fulfillment discarded by merchant |
| MANUAL_REVIEW | FULFILLMENT_ORDER | Fulfillment in manual review state.  |
| CANCELLED | FULFILLMENT_ORDER | Fulfillment cancelled by the merchant |
| INITIATED | FULFILLMENT_TXN | Transaction initiated to the payment gateway |
| FAILURE | FULFILLMENT_TXN | Transaction failed |
| SUCCESS | FULFILLMENT_TXN | Transaction processed successfully |
| REVERSED | FULFILLMENT_TXN | Transaction marked as failure from success by the payment gateway |
| CONFLICTED | FULFILLMENT_TXN | Transaction marked as success from failure by the payment gateway |
| MANUAL_REVIEW | FULFILLMENT_TXN | Transaction stuck in pending state |
| VALID | VALIDATION_V2 | Beneficiary added is valid |
| INVALID | VALIDATION_V2 | Beneficiary added is invalid |
| ERROR | VALIDATION_V2 | Beneficiary could not be validated |
| VALID | VALIDATION | Beneficiary added is valid |
| INVALID | VALIDATION | Beneficiary added is invalid |
| ERROR | VALIDATION | Beneficiary could not be validated |
| GATEWAY_SWITCHED | SR_BASED_ROUTING | Gateway switched by Juspay Decider |
| READY_FOR_FULFILLMENT | ORDER | Request received by Juspay |



#### **Webhook Authentication** 



We support Basic HTTP Authentication for your Webhook URL. Using Username and password fields to authenticate the webhook call is mandatory. Please ensure that special characters like @ are not used in username. You can also add customer header as per your requirement

Basic webhook structure 

            {           

              id : webhook_id

            , category : "INFO"

            , label : "VALIDATION_V2"

            , value : validation status

            , info : validation response for a beneId

            }


#### **Handling Failures** 




#### If your server is not reachable and we receive a non-200 response when we are attempting webhook notification, we would mark the webhook notified section in our dashboard as False. Hence, consume webhooks on with 200 response code.



> **Note**
> Although our webhooks are reliable, it is always suggested that you use our Order Status API to poll our systems, in case you do not receive the webhooks in time.
> 
> This will handle the cases where the webhooks could not be notified to your system. The threshold beyond which you start polling our system can be decided basis your business use case.



## Sample Code Snippets:
### Webhook Payload:

#### Order Ready For Fulfilment Code Snippet:

```order ready for fulfilment
{
  "value": "READY_FOR_FULFILLMENT",
  "label": "ORDER",
  "info": {
    "updatedAt": "2020-05-29T07:24:57Z",
    "status": "READY_FOR_FULFILLMENT",
    "orderType": "FULFILL_ONLY",
    "merchantOrderId": "6lQuvBOixfADPpmD",
    "merchantCustomerId": "1421255",
    "id": "95eb968ccdd4f2d9ef31c3e972ca40",
    "createdAt": "2020-05-29T07:24:13Z",
    "amount": 10
  },
  "id": "5ed06807a0f429e8891847811bd050",
  "category": "INFO"
}

```

#### Order Fulfillment Scheduled Code Snippet:

```order fulfillment scheduled
{
  "value": "FULFILLMENTS_SCHEDULED",
  "label": "ORDER",
  "info": {
    "updatedAt": "2020-05-29T07:24:57Z",
    "status": "FULFILLMENTS_SCHEDULED",
    "orderType": "PAY_AND_FULFILL",
    "merchantOrderId": "6lQuvBOixfADPpmD",
    "merchantCustomerId": "shubham",
    "id": "95eb968ccdd4f2d9ef31c3e972ca40",
    "createdAt": "2020-05-29T07:24:13Z",
    "amount": 10
  },
  "id": "41f0a24aefc4b83936c951dafcf498",
  "category": "INFO"
}

```

#### Order Fulfillment Success Code Snippet:

```order fulfillment success
{
  "value": "FULFILLMENTS_SUCCESSFUL",
  "label": "ORDER",
  "info": {
    "updatedAt": "2020-05-29T07:26:03Z",
    "status": "FULFILLMENTS_SUCCESSFUL",
    "orderType": "PAY_AND_FULFILL",
    "merchantOrderId": "6lQuvBOixfADPpmD",
    "merchantCustomerId": "shubham",
    "id": "95eb968ccdd4f2d9ef31c3e972ca40",
    "createdAt": "2020-05-29T07:24:13Z",
    "amount": 10
  },
  "id": "12d83c7fbc041c2b1290106e6d963f",
  "category": "INFO"
}

```

#### Fulfilment Success Code Snippet:

```fulfilment success
{
  "value": "SUCCESS",
  "label": "FULFILLMENT_ORDER",
  "info": {
    "updatedBy": "DEFAULT",
    "updatedAt": "2020-05-29T07:26:08Z",
    "type": "ORDER",
    "statusUpdatedAt": "2020-05-29T07:26:03Z",
    "status": "SUCCESS",
    "preferredMethodList": ["DUMMY_IMPS"],
    "id": "95eb968ccdd4f2d9ef31c3e972ca40-f1",
    "createdAt": "2020-05-29T07:24:14Z",
    "beneficiaryDetails": {
      "details": {
        "name": "Shubham Kumar",
        "ifsc": "YESB0000262",
        "account": "026291800001191"
      },
      "type": "ACCOUNT_IFSC"
    },
    "amount": 10,
    "merchantCustomerId": "shubham"
  },
  "id": "76f029fd6244fe38a252e54e5707cc",
  "category": "INFO"
}

```

#### Fulfilment Pending Code Snippet:

```fulfilment pending
{
  "value": "INITIATED",
  "label": "FULFILLMENT_ORDER",
  "info": {
    "updatedBy": "DEFAULT",
    "updatedAt": "2020-05-29T07:26:08Z",
    "type": "ORDER",
    "statusUpdatedAt": "2020-05-29T07:26:03Z",
    "status": "PENDING",
    "preferredMethodList": ["DUMMY_IMPS"],
    "id": "95eb968ccdd4f2d9ef31c3e972ca40-f1",
    "createdAt": "2020-05-29T07:24:14Z",
    "beneficiaryDetails": {
      "details": {
        "name": "Shubham Kumar",
        "ifsc": "YESB0000262",
        "account": "026291800001191"
      },
      "type": "ACCOUNT_IFSC"
    },
    "amount": 10,
    "merchantCustomerId": "shubham"
  },
  "id": "9f708e612374de0a6151987a5ad286",
  "category": "INFO"
}

```

#### Transaction Initiated Code Snippet:

```transaction initiated
{
  "value": "INITIATED",
  "label": "FULFILLMENT_TXN",
  "info": {
    "updatedAt": "2020-05-29T07:26:32Z",
    "txnResponse": {
      "status": "PENDING",
      "requestId": "3ec3d5491604fa39d22bba6f236f38",
      "amount": 10
    },
    "transactionRef": "3ec3d5491604fa39d22bba6f236f38",
    "status": "INITIATED",
    "id": "95eb968ccdd4f2d9ef31c3e972ca40-f1-t1",
    "gatewayRefId": "3ec3d5491604fa39d22bba6f236f38",
    "fulfillmentMethod": "DUMMY_IMPS",
    "createdAt": "2020-05-29T07:26:18Z",
    "attempted": true,
    "amount": 10,
    "FulfillmentId": "95eb968ccdd4f2d9ef31c3e972ca40-f1"
  },
  "id": "b3f1e1de9774b559a327d17592df38",
  "category": "INFO"
}

```

#### Transaction Success Code Snippet:

```transaction success
{
  "value": "SUCCESS",
  "label": "FULFILLMENT_TXN",
  "info": {
    "updatedAt": "2020-05-29T07:28:00Z",
    "txnResponse": {
      "status": "SUCCESS",
      "requestId": "3ec3d5491604fa39d22bba6f236f38",
      "amount": 10
    },
    "transactionRef": "3ec3d5491604fa39d22bba6f236f38",
    "status": "SUCCESS",
    "id": "95eb968ccdd4f2d9ef31c3e972ca40-f1-t1",
    "gatewayRefId": "3ec3d5491604fa39d22bba6f236f38",
    "fulfillmentMethod": "DUMMY_IMPS",
    "createdAt": "2020-05-29T07:26:18Z",
    "attempted": true,
    "amount": 10,
    "FulfillmentId": "95eb968ccdd4f2d9ef31c3e972ca40-f1"
  },
  "id": "e0dbf4b217e4530bf202091bb1f653",
  "category": "INFO"
}

```

#### Validation_V2 VALID Code Snippet:

```validation_v2 valid
{"success":false,"message":"No Data found for the given path"}
```

#### Validation_V2 INVALID Code Snippet:

```validation_v2 invalid
{"success":false,"message":"No Data found for the given path"}
```

#### Validation_V2 ERROR Code Snippet:

```validation_v2 error
{
    "value": "ERROR",
    "label": "VALIDATION_V2",
    "info": {
        "validationType": "PENNYLESS",
        "createdAt": "2024-10-09T14:53:22Z",
        "status": "ERROR",
        "transactions": [
            {
                "createdAt": "2024-10-09T14:53:22Z",
                "status": "ERROR",
                "transactionRef": "afba189d09240469f652c6a5ce76a4",
                "updatedAt": "2024-10-09T14:53:23Z",
                "gatewayRefId": "428320000745",
                "responseMessage": "UNABLE_TO_VALIDATE",
                "validateResp": {
                    "clientRefId": "afba189d09240469f652c6a5ce76a4",
                    "transDateTime": "09/10/2024 20:23:23",
                    "rrn": "428320000745",
                    "status": "FAILURE",
                    "responseMsg": "ISSUER NODE OFFLINE",
                    "beneficiaryName": "",
                    "responseCode": "08"
                },
                "validationMethod": "NSDL'JUSPAY_PNL",
                "responseCode": "UNABLE_TO_VALIDATE"
            }
        ],
        "updatedAt": "2024-10-09T14:53:22Z",
        "uniqueId": "PIP091024pRA6zHSfA",
        "responseMessage": "UNABLE_TO_VALIDATE",
        "beneDetails": {
            "details": {
                "ifsc": "CIUB0000507",
                "account": "***************"
            },
            "type": "ACCOUNT_IFSC"
        },
        "responseCode": "UNABLE_TO_VALIDATE"
    },
    "id": "ab90a68c8ed4059beb7acce805edd8",
    "category": "INFO"
}

```