Webhook configuration

Introduction

In order to quickly get set up and begin consuming our webhook events, we've provided examples of the necessary APIs below as CURL commands that you can call to manage your webhook settings.

You will first need to obtain an access token from our authorisation service, details of which can be found here Access Tokens. It is required to have a scope containing "users" when obtaining your token to be able to access these APIs.

User vs Participant webhooks

There are two options available when it comes to setting a receiving webhook endpoint in your account. You can set a url at User level or at Participant level. If you set a webhook address at User level, then any Participants within your account will automatically receive webhooks events sent to the endpoint set against the User. This can be set using the following API:

https://test.api.ordopay.com/config/webhooks/user

If you prefer to have more a granular approach, then you can set different webhook endpoints against each participant using the participant equivalent of our APIs:

https://test.api.ordopay.com/config/webhooks/participant

It is also possible to have webhook endpoints set at both participant and user level, in which case the participant endpoint will take precedence over the user if it exists against a participant, otherwise it will default to the user endpoint.

For an overview of Users and Participants please visit our Glossary

User

Setting a user webhook endpoint

When you're ready to set your webhook receiving endpoint url, you can run the CURL command below to quickly set your settings. Your user_id will be provided to you as part of your onboarding process.

curl -X POST \
  -H "Authorization: Bearer {auth_token}" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Ocp-Apim-Subscription-Key: {subscription_key}" \
  -H "participantId: {participant_id}" \
  -d '{"userId": {user_id}, "callbackUrl": "https://example.com/your_webhook_url", "isActive": true}' \
  https://test.api.ordopay.com/config/webhooks/user

Retrieving a user webhook endpoint

Should you quickly wish to check what values you currently have set in our platform for your webhook config, you can run the CURL command below to quickly retrieve these values.

curl -X GET \
  -H "Authorization: Bearer {auth_token}" \
  -H "Accept: application/json" \
  -H "Ocp-Apim-Subscription-Key: {subscription_key}" \
  -H "userId: {user_id}" \
  https://test.api.ordopay.com/config/webhooks/user

Deleting a user webhook endpoint

If for any reason you wish to delete your webhook config, you can run the below CURL command to quickly remove these from our platform. It is also worth noting that should you wish to update your webhook config, you must delete your existing settings first and then call our POST with your updated values.

curl -X DELETE \
  -H "Authorization: Bearer {auth_token}" \
  -H "Accept: application/json" \
  -H "Ocp-Apim-Subscription-Key: {subscription_key}" \
  -H "userId: {user_id}" \
  https://test.api.ordopay.com/config/webhooks/user

Participant

Setting a participant webhook endpoint

When you're ready to set your webhook receiving endpoint url, you can run the CURL command below to quickly set your settings.

curl -X POST \
  -H "Authorization: Bearer {auth_token}" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Ocp-Apim-Subscription-Key: {subscription_key}" \
  -H "participantId: {participant_id}" \
  -d '{"participantId": {participant_id}, "callbackUrl": "https://example.com/your_webhook_url", "isActive": true}' \
  https://test.api.ordopay.com/config/webhooks/participant

Retrieving a participant webhook endpoint

Should you quickly wish to check what values you currently have set in our platform for your webhook config, you can run the CURL command below to quickly retrieve these values.

curl -X GET \
  -H "Authorization: Bearer {auth_token}" \
  -H "Accept: application/json" \
  -H "Ocp-Apim-Subscription-Key: {subscription_key}" \
  -H "participantId: {participant_id}" \
  https://test.api.ordopay.com/config/webhooks/participant

Deleting a participant webhook endpoint

If for any reason you wish to delete your webhook config, you can run the below CURL command to quickly remove these from our platform. It is also worth noting that should you wish to update your webhook config, you must delete your existing settings first and then call our POST with your updated values.

curl -X DELETE \
  -H "Authorization: Bearer {auth_token}" \
  -H "Accept: application/json" \
  -H "Ocp-Apim-Subscription-Key: {subscription_key}" \
  -H "participantId: {participant_id}" \
  https://test.api.ordopay.com/config/webhooks/participant