# Receive Event Notifications (Webhooks)

## Subscribe to certain event types

### Business Goal

Allow customers to subscribe to real-time inbound/outbound payment and T-bill maturity events via webhooks. By subscribing to these events, customers can eliminate the need for constant polling and automate downstream workflows such as reconciliation, settlement processing, maturity handling, and notifications.

The table below lists the Jiko webhook used to monitor transfers:

| Payment Rail | Direction | Event types |
|  --- | --- | --- |
| Wire, Swift | Outbound | • `transfers.wire.out.processing` • `transfers.wire.out.success` • `transfers.wire.out.rejected` |
| Wire, Swift | Inbound | • `transfers.wire.in.success` • `transfers.wire.in.rejected` (funds received but had to be returned) |
| JikoNet, Same-entity transfer | Outbound | • `transfers.on-us.processing` • `transfers.on-us.success` • `transfers.on-us.rejected` |
| JikoNet, Same-entity transfer | Inbound | • `transfers.on-us.received` |


Example of webhook result notifying about an incoming JikoNet transfer (on-us transfer):


```json
{
  "event_id": "94444752-cfa7-5d08-a2da-7f42ffdc649c",
  "event_type": "transfers.on-us.received",
  "timestamp": "2026-01-30T16:09:35.775108Z",
  "payload": {
    "on_us_id": "bf01c8e4-f42d-4ccf-9c54-57bc25524ee4",
    "transaction_activity_id": "15dfbc4b-5343-4d5d-9230-ff788d034c33",
    "receiving_pocket_id": "744ab7f4-e94f-433b-9224-01cbe6585c12"
  },
  "customer_id": "0b5b74f5-ad65-4c6d-9170-60fe29794b12"
}
```

Where the payload includes a `wire_id` or a `on_us_id` that can be used to get the corresponding transfer details using GET [`/api/v1/transfer-requests/{transfer_id}/`](/products/customer-api/reference/transfer-requests/get_transfer_request_api_v1_transfer_requests__transfer_id___get), passing this `wire_id` or a `on_us_id` as `{transfer_id}` parameter.

### Business Workflow Example

Customer systems:

1. Define the events to receive.
2. Configure a secure webhook endpoint in the customer's system to receive event notifications.
3. Call Jiko's subscription endpoint to subscribe to event notification, passing the customer's webhook URL to notify.
4. Receive real-time event payloads as activities occur on Jiko's platform.
5. Process incoming events to trigger downstream workflows such as reconciliation, settlements, or notifications.
6. Monitor delivery success and handle retries, errors, or updates to the subscription as needed.


### Relevant API Endpoints

| Step | Purpose | Jiko API Endpoints |
|  --- | --- | --- |
| 1 | Create a new webhook subscription to receive real-time notifications for a set of events. | POST [`/api/v1/subscriptions/`](/products/customer-api/reference/subscriptions/create_subscription_api_v1_subscriptions__post) |