--- updatedAt: 2026-04-22T22:43:18.000Z agentTools: projectIndex: https://developers.akahu.nz/llms.txt --- # Subscribe to webhook > ℹī¸ > > Akahu's webhooks are unusual in that they need to be initialised **per user**, requiring a new webhook subscription for each event type you wish to receive for each user. Register a new webhook subscription for the user, allowing your application to receive events on the following webhook types: - `TOKEN` - `ACCOUNT` - `TRANSACTION` - `PAYMENT` - `TRANSFER` > ℹī¸ > > It is a good idea to use the `state` field to store a unique identifier related to your end user, allowing you to determine on an arrival of a webhook event which user of your application needs to be updated or notified. For more details about webhooks see: - [📖 Webhooks reference](/docs/reference-webhooks) - [📖 Webhooks events](/reference-webhooks#token) # OpenAPI definition ```json { "openapi": "3.1.0", "info": { "title": "Akahu Enduring API", "description": "This API is the primary way for apps to interact with a user's data.", "version": "1.0.0" }, "servers": [ { "url": "https://api.akahu.io/v1" } ], "components": { "parameters": { "xAkahuId": { "name": "X-Akahu-Id", "in": "header", "required": true, "description": "Your **App ID Token**.", "schema": { "type": "string" }, "example": "{{app_token}}" }, "ContentType": { "name": "Content-Type", "in": "header", "schema": { "type": "string" }, "example": "application/json" } }, "securitySchemes": { "user_token": { "type": "http", "scheme": "bearer", "description": "User-level Authentication:\n\nHttp Bearer Auth with the token being a consented **User Access Token**.\n> `Bearer {user_token}`\n\nThis will allow you to act on a **user's** behalf when accessing the API." } }, "responses": { "401": { "description": "You are not authorised to access this content.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Permission Denied" } } } } } }, "403": { "description": "You are not allowed to access this content.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Forbidden" } } } } } }, "500": { "description": "An internal error has prevented us from processing the request. More detail may be supplied in the `message` key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Something went wrong" } } } } } } } }, "tags": [ { "name": "Webhooks" } ], "paths": { "/webhooks": { "post": { "tags": [ "Webhooks" ], "summary": "Subscribe to webhook", "security": [ { "user_token": [] } ], "description": "> ℹī¸\n>\n> Akahu's webhooks are unusual in that they need to be initialised **per user**, requiring a new webhook subscription for each event type you wish to receive for each user.\n\nRegister a new webhook subscription for the user, allowing your application to receive events on the following webhook types:\n\n - `TOKEN`\n - `ACCOUNT`\n - `TRANSACTION`\n - `PAYMENT`\n - `TRANSFER`\n\n> ℹī¸\n>\n> It is a good idea to use the `state` field to store a unique identifier related to your end user, allowing you to determine on an arrival of a webhook event which user of your application needs to be updated or notified.\n\n\nFor more details about webhooks see:\n - [📖 Webhooks reference](/docs/reference-webhooks)\n - [📖 Webhooks events](/reference-webhooks#token)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "webhook_type": { "type": "string", "description": "Which types of events you want to receive webhooks for." }, "state": { "type": "string", "description": "State that will be returned with the webhook payload." } } }, "examples": { "Token Webhook": { "summary": "Token Webhook", "value": { "webhook_type": "TOKEN", "state": "foobarbaz" } }, "Account Webhook": { "summary": "Account Webhook", "value": { "webhook_type": "ACCOUNT", "state": "foobarbaz" } }, "Transaction Webhook": { "summary": "Transaction Webhook", "value": { "webhook_type": "TRANSACTION", "state": "foobarbaz" } }, "Payment Webhook": { "summary": "Payment Webhook", "value": { "webhook_type": "PAYMENT", "state": "foobarbaz" } } } } } }, "parameters": [ { "$ref": "#/components/parameters/xAkahuId" }, { "$ref": "#/components/parameters/ContentType" } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "item_id": { "type": "string", "description": "Newly created Akahu webhook identifer.", "example": "hook_1111111111111111111111111" } } } } } }, "400": { "description": "Your request was malformed or otherwise unacceptable. The `message` key in the response will give more details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" } } }, "examples": { "invalid_type": { "summary": "Invalid Webhook Type", "description": "The specified webhook type doesn't exist.", "value": { "success": false, "message": "Invalid webhook_type" } }, "app_missing_destination": { "summary": "App Not Setup", "description": "Your app has not been setup with a webhook destination URL.", "value": { "success": false, "message": "App is missing webhook url" } } } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "500": { "$ref": "#/components/responses/500" } } } } } } ```