Skip to main content

How to set up a webhook

Pre-requisites:​

  • Ensure to authenticate all request using the API key.
  • You need a valid and reachable URL to receive webhook notifications.
  • Use secure connections (HTTPS) for webhook URLs to ensure data integrity and security.

Register your webhook​

Use the following endpoints to register your URL

curl -X POST "https://staging-api.payments.ai/v1/webhook-destinations" \
     -H "Authorization: ApiKey your_api_key_here" \
     -H "Content-Type: application/json" \
     -d '{
           "url": "https://your-url-here.com/webhook",
           "auth": {
             "type": "basic",
             "username": "user",
             "password": "pass"
           }
         }'

Webhook registration response​

If the registration is successful, you will receive a response with the following details:

HTTP Status code 201

{
  "type": "object",
  "data": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "createdAt": "2019-08-24T14:15:22Z",
    "updatedAt": "2019-08-24T14:15:22Z",
    "url": "string",
    "auth": {
      "type": "basic",
      "username": "string",
      "password": "string"
    }
  }
}

Debugging registration:​

  • HTTP Status code 400 - Your payload is incorrect (wrong data)

    {
      "errorCode": "string",
      "statusCode": 400,
      "message": "Bad request",
      "details": "string"
    }

  • HTTP Status code 401 - there is a problem with your Authorization API key

    {
      "errorCode": "string",
      "statusCode": 401,
      "message": "Missing auth token"
    }

  • HTTP Status code 403 - forbidden access

    {
      "errorCode": "string",
      "statusCode": 403,
      "message": "Forbidden access"
    }

  • HTTP Status code 500 - internal server error

    {
      "errorCode": "string",
      "statusCode": 500,
      "message": "Internal server error"
    }

    You can find all webhooks endpoint in the Webhooks API Documentation.

Validate your webhook​

To validate your webhook, you send HTTP GET request.

curl -X GET "https://staging-api.payments.ai/v1/webhook-destinations/:webhookID" \
     -H "Authorization: ApiKey your_api_key_here" \
     -H "Accept: application/json"

Test your webhook​

To test your webhook, you can send a HTTP POST request to create a new transaction.

curl -X POST "https://staging-api.payments.ai/v1/organizations/:organizationID/transactions" \
     -H "Authorization: ApiKey your_api_key_here" \
     -H "Content-Type: application/json" \
     -d '{
          "type": "sale",
          "customerId": "string",
          "currency": "AED",
          "amount": 0,
          "paymentInstruction": {
          "token": "string"
          }
         }'

If the webhook has been successfully registered, you will receive a webhook event response with the following details:

type Event = {
  deduplicationId: string; // unique identifier for the event, used to prevent duplicate events
  type: string;
  organizationId: string;
  metadata: {
    amount: number;
    refundAmount: number | undefined;
    refundableAmount: number;
    currency: string; // USD, EUR, etc.
    status: TransactionStatus;
    result: TransactionResult;
    combinedStatus: TransactionResultStatusCombined | undefined;
    customer: Customer;
    date: Date;
    type: TransactionType;
    paymentType: 'one-time-payment' | 'subscription-payment';
    paymentInstrument: PaymentInstrument | null;
    invoices: Invoice[];
    gatewayName: string;
    gatewaySlug: string | null;
    subscriptionId: string | undefined;
    paymentLink: string | undefined;
    approvalLink: string | undefined;
    permissionBundle: TransactionPermissionsBundle;
    isProcessedOutside: boolean;
    refundedAt: Date | undefined;
  };
};

Additional endpoints​

You can find all webhook related endpoints in the Webhooks API Documentation.

Get Your webhook destinations​

curl -X GET "https://staging-api.payments.ai/v1/webhook-destinations" \
     -H "Authorization: ApiKey your_api_key_here" \
     -H "Accept: application/json"

Get webhook destination by ID​

curl -X GET "https://staging-api.payments.ai/v1/webhook-destinations/:webhookID" \
     -H "Authorization: ApiKey your_api_key_here" \
     -H "Accept: application/json"

Update webhook destination​

curl -X PATCH "https://staging-api.payments.ai/v1/webhook-destinations/:webhookID" \
     -H "Authorization: ApiKey your_api_key_here" \
     -H "Content-Type: application/json" \
     -d '{
           "url": "https://newexample.com/webhook",
           "auth": {
             "type": "basic",
             "username": "newuser",
             "password": "newpass"
           }
         }'

Delete webhook destination​

curl -X DELETE "https://staging-api.payments.ai/v1/webhook-destinations/:webhookID" \
     -H "Authorization: ApiKey your_api_key_here"

Learn more about webhooks in the Webhooks Documentation and Explore the Webhooks API Documentation.