Webhook API

Environments & authentication

The Webhook API uses the same environments as the Collection API. All requests must use HTTPS. Keep sandbox and production configuration separate.

Required request headers

Obtain your merchant credentials from the Developer section of your 3ribe dashboard. Send these headers for both setup and retrieval.

apikey: YOUR_API_KEY
apisecretkey: YOUR_API_SECRET_KEY
Content-Type: application/json

Endpoint reference

The endpoint summary and sandbox examples document the following routes.

Setup webhook URL

Register or configure the HTTPS webhook URL associated with your merchant account. 3ribe validates the URL and returns the configuration result. An HTTP receiver URL will not be accepted.

{
  "webHookUrl": "https://localhost:44374/api/collection/setupwebhook"
}

Request parameter

Successful setup

{
  "responseMessage": "Webhook Url set up is successful!",
  "responseStatus": true
}

Failed setup · HTTPS required

{
  "responseMessage": "Webhook Url must be a secured url with https",
  "responseStatus": false
}

Failure condition: responseStatus is false. Ensure the receiver URL begins with https:// and submit the setup request again.

Try it in Postman

1. 01Set the method to POST and the sandbox request URL to {{baseurl}}/api/collection/setupwebhook, with {{baseurl}} set to the sandbox host above.
2. 02Add apikey, apisecretkey and Content-Type: application/json in Headers.
3. 03In Body, choose raw and JSON. Submit the webHookUrl request shown above with your intended receiver URL and inspect responseStatus.

Get webhook URL

Retrieve the webhook URL configured for the authenticated merchant account. The merchant credentials identify the account. The supplied specification requires no request body.

Successful retrieval

{
  "responseMessage": "Webhook Url retrieved successful!",
  "responseStatus": true,
  "webHookUrl": "https://localhost:44374/api/collection/setupwebhook"
}

Failed retrieval · not configured

{
  "responseMessage": "Webhook url not set up",
  "responseStatus": false,
  "webHookUrl": ""
}

When no webhook URL is configured, responseStatus is false, responseMessage explains that setup is missing and webHookUrl is an empty string. Call Setup Webhook URL to register a receiver.

Try it in Postman

1. 01Set the method to GET and use {{baseurl}}/api/collection/getwebhook with the sandbox base URL.
2. 02Add the same three authentication and content-type headers. Leave the request body empty.
3. 03Send the request. Confirm responseStatus is true and compare webHookUrl with the endpoint you intended to register.

Configuration sequence

Configure the receiver first, then verify that 3ribe has stored the correct URL for the merchant.

1. 01Develop and deploy a webhook receiver on your backend. Ensure it is publicly accessible over HTTPS and can accept incoming HTTP requests.
2. 02Call Setup Webhook URL with your merchant API credentials. Put the intended receiver address in the exact webHookUrl field.
3. 03Inspect the setup response and confirm responseStatus is true. Log the configuration result for troubleshooting and audit.
4. 04Call Get Webhook URL using the same merchant credentials.
5. 05Confirm the returned webHookUrl matches your intended endpoint. Retrieve it periodically to check the registered configuration.

Security & event contract

Secure the management integration

Incoming notifications · details to confirm

This reference covers webhook management only. The source does not provide an incoming notification implementation contract. Obtain the following details from 3ribe rather than assuming a schema or delivery behaviour.