Set up a callback endpoint

This guide explains how to create and register a callback endpoint for receiving and processing callback messages from the Cobo payments service.

​

Create an endpoint

Choose a server environment that supports receiving and processing HTTP POST requests, such as a cloud service like AWS or Google Cloud, or a self-hosted server. Define an endpoint URL on your server where Cobo will send callback messages.

​

Implement handling logic

After you create the endpoint, implement the logic on your server to handle callback messages.

​

Parse the callback request

Cobo sends an HTTP POST request to your registered callback endpoint. The request body is the transaction object and contains the following fields:

​

Verify the signature

To prevent unauthorized access, verify the authenticity of each callback request by checking its signature. The verification steps are as follows:

1. Retrieve the raw body and timestamp. Extract the original body string from the request payload and the timestamp from the request headers.
   raw_body = request.body().decode('utf8')
   timestamp = request.headers.get("BIZ_TIMESTAMP")
   
2. Retrieve the signature. Fetch the signature value from the request header.
   signature = request.headers.get('BIZ_RESP_SIGNATURE')
   
3. Concatenate and hash the message.
   import hashlib
   
   # Concatenate raw body and timestamp to form the message.
   message = "raw_body|timestamp"
   
   # Compute double SHA-256 hash.
   sha256_hash = hashlib.sha256(hashlib.sha256(message.encode()).digest()).digest()
   
4. Select Cobo’s public key. Depending on the environment you use, select the corresponding public key for verification:
   • Development environment: a04ea1d5fa8da71f1dcfccf972b9c4eba0a2d8aba1f6da26f49977b08a0d2718
   • Production environment: 8d4a482641adb2a34b726f05827dba9a9653e5857469b8749052bf4458a86729
5. Verify the signature using the Ed25519 algorithm.
   import ed25519
   
   # Obtain the verifying key from Cobo's public key.
   vk = ed25519.VerifyingKey(bytes.fromhex(public_key))
   
   # Verify the signature against the computed message hash.
   vk.verify(bytes.fromhex(signature), sha256_hash)
   

​

Respond to the callback request

Your endpoint must respond within 10 seconds. Return a JSON body with a result field:

• To approve the operation:
  {"result": "ok"}
  
• To deny the operation:
  {"result": "deny"}
  

If your endpoint does not respond in time or returns any other response, the callback message status becomes Failed.

​

Register the endpoint

You register a callback URL when creating an API key in Cobo Portal. The callback URL is associated with the API key and Cobo sends callback messages to it for all operations initiated using that API key.

1. Go to Cobo Portal > Developer > API Keys.
2. Click Register API Key.
3. In the Callback URLs section, click Add Callback URLs.
4. Enter your endpoint URL and an optional description.
5. Click Register to save the callback URL.
6. Click Register Key to complete the API key registration.

​

Important notes