Webhook

At Subsidian, we believe in providing you with the most up-to-date information for your transactions. Webhooks are instrumental in achieving this. They serve as a channel through which we can send your application immediate notifications whenever there are changes in your payment events. This allows you to stay on top of your transactions in real-time, ensuring a seamless and efficient experience for both you and your customers.

How Webhooks Work

Asynchronous Event Handling: Webhooks excel in handling asynchronous events. When a transaction event occurs, such as a successful payment, our system triggers a webhook to notify your application.

Efficient Transaction Tracking: Webhooks are a powerful tool for tracking transactions efficiently. By receiving real-time updates, you can keep a close eye on every step of the payment process.

Customer-Initiated Payments: Beyond tracking, webhooks empower you to initiate payments directly from the customer. This opens up a world of possibilities for seamless, customer-driven transactions.

Setting Up Webhooks

Access Your Business Dashboard: Log in to your Subsidian Business Dashboard and navigate to the 'Apps' section.

Configuring Webhooks: Within the Apps section, you can easily set up webhooks for various event types. This allows you to customize the notifications you receive.

Webhook URL Configuration: Define the URL where you want to receive webhook notifications. This URL should be the endpoint in your application that is ready to receive and process webhook data.

Event Types: Choose the specific event types that you want to receive notifications for. This customization ensures that you get the information that matters most to your business.

Webhook Events Overview

We currently support the following event types:

Events

Description

TRANSACTION

Transaction state changes when the customer is paying.

SUBSCRIPTION

Unavailable: Subscription payments

PAYMENT LINKS

Unavailable: Payments on a payment link

INVOICES

Unavailable: Invoice Payments

Sample Message

All webhook messages you receive from us will follow this general format

{
  "id": "90ba2e17-962e-42c0-bc05-312e7e969cef",
  "event": "TRANSACTION_COMPLETED",
  "data": {
    "messageType": "0200",
    "primaryAccountNumber": "536902******4659",
    "processingCode": "090000",
    "transactionAmount": "222",
    "transmissionDateTime": "0906191950",
    "settlementConversionRate": "",
    "systemTraceAuditNumber": "831391",
    "localTime": "191950",
    "localDate": "0906",
    "expirationDate": "****",
    "settlementDate": "",
    "conversionDate": "",
    "merchantType": "5666",
    "posEntryMode": "051",
    "cardSequenceNumber": "000",
    "posConditionCode": "00",
    "posPinCaptureCode": "06",
    "transactionFeeAmount": "C00000000",
    "settlementAmount": "",
    "transactionProcessingFeeAmount": "",
    "settleProcessingFeeAmount": "",
    "acquiringInstitutionId": "111129",
    "forwardingInstitutionId": "",
    "trackTwoData": "*************************************",
    "retrievalReferenceNumber": "324983139142",
    "authorizationIdResponse": "",
    "responseCode": "",
    "serviceRestrictionCode": "226",
    "cardAcceptorTerminalId": "9801C039",
    "cardAcceptorIdCode": "8259DE490845751",
    "cardAcceptorNameLocation": "CLANE COMPANY NIGERIA LIM           IMNG",
    "additionalResponseData": "",
    "additionalData": "",
    "transactionCurrencyCode": "566",
    "settlementCurrencyCode": "",
    "pinData": "",
    "securityRelatedControlInformation": "",
    "additionalAmounts": "0002566C000000000100",
    "integratedCircuitCardData": "****************************************************************************************************************************************************************************************************************************************************************************************************************************************************************************************************************************************************************************************************************************************************************************************************************************",
    "messageReasonCode": "",
    "authorizingAgentId": "",
    "transportEchoData": "0:78992678-babf-4ba4-86b1-eed71d4a3ccf,1:23-09-06 19:19:50,2:DOE/ALO,3:A0000000041010,4:9801C039,5:100,6:OFFLINE",
    "paymentInformation": "",
    "managementDataOnePrivate": "",
    "managementDataTwoPrivate": "",
    "primaryMessageHashValue": "",
    "extendedPaymentCode": "",
    "originalDataElement": "",
    "replacementAmount": "",
    "payee": "",
    "receivingInstitutionId": "",
    "accountIdentification1": "",
    "accountIdentification2": "",
    "posDataCode": "510101511344101",
    "nearFieldCommunicationData": "",
    "secondaryMessageHashValue": "2C5BAE01942FEF3446499EB09D089D34"
  },
  "merchantId": "8259DE490845751",
  "paymentReference": "324983139142",
  "channel": "CARD",
  "failedCount": 0,
  "timestamp": 1699222682523
}

Field Descriptions

uuid: A unique identifier for the event (transaction reference, invoice reference, etc.).

timestamp: The time at which the event action occurred.

event: Describes the event that occurred, triggering the notification.

data: Contains the relevant object (Payment Object).

Sending Back Response

Upon receiving a message, it is crucial to respond with a 200 HTTP status code. This confirms that you have received the message. If any HTTP response code other than 200 is returned, it is assumed that the message was not received, and up to five retries will be attempted.

Do not include a response body with the 200 HTTP response; any response body sent will be disregarded.

Additionally, it is important to respond with a 200 immediately upon message receipt, before initiating any other lengthy processes. This precaution is necessary to prevent potential duplicate data due to retry attempts.

Message Security

All webhook messages sent from us are hashed using the HmacSHA512 Algorithm. This hash is generated using the entire object received in the current notification.

The secret key used for hashing is the unique one generated for you during configuration.

The generated hash is then Hex encoded and passed in the header as the parameter field X-Subsidian-Signature.

This process ensures that you can verify the authenticity of any message received on your configured URL.

To verify each message, follow these steps:

Generate another hash using the same algorithm (Hmacsha512), your secret key, and the raw JSON object received as a string.

Compare the generated hash to the one passed in the X-Subsidian-Signature header.

Example:

If the request body sent to you is:

{
  "event": "TRANSACTION_COMPLETED",
  "uuid": "2Xdf35faAyX2Sk5Dalu405rUD",
  "timestamp": 1594646111460,
  "data": { ... }
}

The hash will be hex-encoded with your secret key

HmacSHA512 ( {"event": "TRANSACTION.UPDATED", "uuid": "2Xdf35faAyX2Sk5Dalu405rUD", "timestamp": 1594646111460, "data": { "bankCode": "011" } } )

If the generated hash does not match the hash received in the X-Subsidian-Signature header, the request was not sent by us.

Furthermore, any request received without the X-Subsidian-Signature header is also not from us.

post

Body

idinteger · int64Required

merchantIdstringRequired

urlstringRequired

secretKeystringRequired

activebooleanRequired

Responses

200

*/*

404

Not Found

*/*

post

/api/v1/webhook

POST /api/v1/webhook HTTP/1.1
Host: localhost:8080
Content-Type: application/json
Accept: */*
Content-Length: 74

{
  "id": 1,
  "merchantId": "text",
  "url": "text",
  "secretKey": "text",
  "active": true
}

{
  "id": 1,
  "merchantId": "text",
  "url": "text",
  "secretKey": "text",
  "active": true
}

put

Body

idinteger · int64Required

merchantIdstringRequired

urlstringRequired

secretKeystringRequired

activebooleanRequired

Responses

200

*/*

404

Not Found

*/*

put

/api/v1/webhook

PUT /api/v1/webhook HTTP/1.1
Host: localhost:8080
Content-Type: application/json
Accept: */*
Content-Length: 74

{
  "id": 1,
  "merchantId": "text",
  "url": "text",
  "secretKey": "text",
  "active": true
}

{
  "id": 1,
  "merchantId": "text",
  "url": "text",
  "secretKey": "text",
  "active": true
}

delete

Query parameters

idinteger · int64Required

Responses

200

No content

404

Not Found

*/*

delete

/api/v1/webhook

DELETE /api/v1/webhook?id=1 HTTP/1.1
Host: localhost:8080
Accept: */*

No content

get

Path parameters

idstringRequired

Responses

200

*/*

404

Not Found

*/*

get

/api/v1/webhook/{id}

GET /api/v1/webhook/{id} HTTP/1.1
Host: localhost:8080
Accept: */*

{
  "id": 1,
  "merchantId": "text",
  "url": "text",
  "secretKey": "text",
  "active": true
}

PreviousAuthenticate NextDevice Management

Last updated 2 years ago

Was this helpful?