> ## Documentation Index > Fetch the complete documentation index at: https://apidocs.paylias.xyz/llms.txt > Use this file to discover all available pages before exploring further. # Update Webhook > Webhooks can be updated by provinding the below listed parameters. Setting a webhook secret allows you to ensure that `POST` requests sent to the payload URL are from GitHub. When you set a secret, you'll receive the `X-PAYLIAS-SIGNATURE` header in the webhook `POST` request. The `add_events` array allows your webhook to subscribe to additional events while the `remove_events` array will unsubscribe the events from your webhook. Please note that the uniqueness constraint from the section above still applies. ## OpenAPI ````yaml put /api/v1/csp/webhook/{webhook_id} openapi: 3.1.0 info: title: Paylias API description: >- Paylias is a network that enables developers to orchestrate money movement between different financial institutions with ease and speed. The Paylias API makes it simple for financial platforms to issue virtual addresses, manage connections and exchange value by sending and receiving money. Our API is based upon REST principles, returns JSON responses, and uses standard HTTP response codes. version: 0.1.0 contact: {} servers: - url: https://sandbox.api.paylias.xyz/gateway security: [] tags: - name: API Authentication description: >- For server-to-server communication, Paylias supports authentication through JWT tokens as well as API keys. All APIs that are that deal with the `Organization` resource are authenticated using JWT tokens, while the rest of the system uses API Keys to authenticate To use a JWT token, set the Authorization header to `Bearer`. To use an API key, set a header called `X-PAYLIAS-API-KEY` and use the API key as the value. ## JWT token When making requests to Paylias from a browser, you can use JSON Web Tokens (JWT). This requires the credentials of a user that has admin access. The validity of JWT tokens issued by Paylias is 7 days. ## API key Longer lasting access tokens can be generated with fine grained permissions using the Create API key endpoint. These access tokens can be rotated, revoked and updated through the browser as well. API Keys are linked to a Namespace to allow finer access controls when dealing with API requests using long lived tokens. While account admins can take actions on API keys from the dashboard, the `X-Partner-ID` header must be set to the id of the Namespace for which the API key was originally issued against. - name: Organizations description: >- In the Paylias network, an `Organization` represents a legal entity, specifically a financial institution. It stands at the top of the system's hierarchy, overseeing sub-entities like `api keys`, `webhooks`, and `partners`. Given its financial nature, the Paylias network has certain verification processes to fulfill. When users join the Paylias dashboard, they initially receive an account in a sandboxed environment. This phase allows for familiarization without impacting the main system. Full access is granted once a member of the Paylias team validates and completes all necessary formalities for the user. For efficient management, users can either use the dashboard or APIs, with the latter requiring a valid JWT Token for secure interactions. - name: Namespace description: >- A `namespace` is a logical collection of payment addresses that are issued by an `organization`. Payment addresses issued inside a `namespace` will share a common `domain`. The domain helps identify organizations, country of issuance and other specifics around the brand, rewards and configurations. - name: Accounts - name: Validation - name: API Keys description: >- Longer lasting access tokens can be generated with fine grained permissions using the Create API key endpoint. These access tokens can be rotated, revoked and updated through the browser as well. API Keys are linked to a Namespace to allow finer access controls when dealing with API requests using long lived tokens. While account admins can take actions on API keys from the dashboard, the `X-Partner-ID` header must be set to the id of the Namespace for which the API key was originally issued against. - name: Webhooks description: >- Webhooks allow applications to communicate in real-time. When an event occurs, a webhook will deliver the event data to the application determined by the target endpoint. A webhook can be setup to be notified of all event types or specific ones. This allows your application to react to events, which is more efficient than polling an API to determine if an event has occurred. In the Paylias network, webhooks are used to communicate events related to Links and Payments. Similar to API Keys, Webhooks are created against a Namespace and thus require the `X-Partner-ID` header to be set in all requests ## Event types Here are the event types that we capture and send. This may not be a comprehensive list as we are continuing to add events to our system. | **Event Identifier** | **Description** | | --- | --- | | `link.create.resp` | A link request has been processed | | `link.propose.req` | A link request has been proposed | | `link_established` | A link has been established | | `link_update_resp` | A link has been updated | - name: Customers - name: Payments - name: Submissions - name: Admissions - name: Admission Tasks - name: Transactions - name: Settlements description: Settlement batches, partner merkle artefacts, and settlement net positions - name: Exceptions paths: /api/v1/csp/webhook/{webhook_id}: put: tags: - Webhooks summary: Update Webhook description: >- Webhooks can be updated by provinding the below listed parameters. Setting a webhook secret allows you to ensure that `POST` requests sent to the payload URL are from GitHub. When you set a secret, you'll receive the `X-PAYLIAS-SIGNATURE` header in the webhook `POST` request. The `add_events` array allows your webhook to subscribe to additional events while the `remove_events` array will unsubscribe the events from your webhook. Please note that the uniqueness constraint from the section above still applies. operationId: updateWebhook parameters: - $ref: '#/components/parameters/PartnerIdHeader' - $ref: '#/components/parameters/IdempotencyKeyHeader' - $ref: '#/components/parameters/WebhookIdParam' requestBody: $ref: '#/components/requestBodies/UpdateWebhook' responses: '200': $ref: '#/components/responses/WebhookResponse' description: Successful retrieval of a webhook subscription '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' security: - bearerAuth: [] components: parameters: PartnerIdHeader: name: x-partner-id in: header required: true schema: type: string default: '' description: The Partner ID header used for authorization IdempotencyKeyHeader: name: idempotency-key in: header required: true schema: type: string default: '' description: The Idempotency Key - usually a UUID WebhookIdParam: name: webhook_id in: path required: true schema: type: string example: whk_cjf0qivsemvkg2on8f9g description: The unique identifier for the webhook requestBodies: UpdateWebhook: description: Request to update an existing webhook content: application/json: schema: type: object properties: description: type: string example: Payment notifications description: Description of the webhook enabled: type: boolean example: true description: Whether the webhook is enabled endpoint: type: string example: https://example.com/webhook description: Endpoint URL of the webhook add_events: type: array description: List of events the webhook subscribes to items: type: object properties: record_type: type: string enum: - RT_PaymentSubmissions - RT_Error - RT_Payments - RT_PaymentAdmissions - RT_PaymentAdmissionTasks - RT_Transactions example: RT_PaymentSubmissions description: Type of record for the event event_type: type: string enum: - EK_Created - EK_Updated example: EK_Created description: Type of event remove_events: type: array description: List of events the webhook subscribes to items: type: object properties: record_type: type: string enum: - RT_PaymentSubmissions - RT_Error - RT_Payments - RT_PaymentAdmissions - RT_PaymentAdmissionTasks - RT_Transactions example: RT_PaymentSubmissions description: Type of record for the event event_type: type: string enum: - EK_Created - EK_Updated example: EK_Created description: Type of event name: type: string example: Payment Webhook description: Name of the webhook secret: type: string example: ASDLKJASDFLKJ121232342 description: Secret for webhook signature verification required: - name - endpoint - events - enabled examples: Update Webhook Subscription: value: name: Payment Webhook endpoint: https://example.com/webhook events: - record_type: RT_PaymentSubmissions event_type: EK_Created - record_type: RT_PaymentSubmissions event_type: EK_Updated enabled: true secret: ASDLKJASDFLKJ121232342 responses: WebhookResponse: description: Response containing Webhook subscription information headers: Content-Length: $ref: '#/components/headers/ContentLengthHeader' Date: $ref: '#/components/headers/DateHeader' X-Csp-Version: $ref: '#/components/headers/CspVersionHeader' X-Partner-Id: $ref: '#/components/headers/PartnerIdHeader' X-Org-Id: $ref: '#/components/headers/OrgIdHeader' content: application/json: schema: allOf: - $ref: '#/components/schemas/StandardResponse' - type: object properties: data: $ref: '#/components/schemas/Webhook' examples: success: value: data: description: Webhook to consume link events endpoint: https://www.postb.in/1743272420303-9920796800870 enabled: false events: - record_type: RT_PaymentSubmissions event_type: EK_Created - record_type: RT_PaymentSubmissions event_type: EK_Updated name: Link Events secret: 2ff46f215a5bb7da8f7fda9b2b0c9ef86c9e7de6 ok: true BadRequest: description: Bad request headers: Content-Length: $ref: '#/components/headers/ContentLengthHeader' Date: $ref: '#/components/headers/DateHeader' X-Csp-Version: $ref: '#/components/headers/CspVersionHeader' content: application/json: schema: allOf: - $ref: '#/components/schemas/ErrorResponse' - type: object properties: code: example: error.bad_request message: example: Invalid request parameters Unauthorized: description: Unauthorized headers: Content-Length: $ref: '#/components/headers/ContentLengthHeader' Date: $ref: '#/components/headers/DateHeader' X-Csp-Version: $ref: '#/components/headers/CspVersionHeader' content: application/json: schema: allOf: - $ref: '#/components/schemas/ErrorResponse' - type: object properties: code: example: error.unauthorized message: example: Authentication required NotFound: description: Resource not found headers: Content-Length: $ref: '#/components/headers/ContentLengthHeader' Date: $ref: '#/components/headers/DateHeader' X-Csp-Version: $ref: '#/components/headers/CspVersionHeader' content: application/json: schema: allOf: - $ref: '#/components/schemas/ErrorResponse' - type: object properties: code: example: error.not_found message: example: Requested resource not found Conflict: description: Resource conflict headers: Content-Length: $ref: '#/components/headers/ContentLengthHeader' Date: $ref: '#/components/headers/DateHeader' X-Csp-Version: $ref: '#/components/headers/CspVersionHeader' content: application/json: schema: allOf: - $ref: '#/components/schemas/ErrorResponse' - type: object properties: code: example: error.conflict message: example: Resource already exists headers: ContentLengthHeader: schema: type: string example: '256' DateHeader: schema: type: string example: Sat, 12 Aug 2023 08:55:04 GMT CspVersionHeader: schema: type: string example: gateway-csp/v1.0.0 PartnerIdHeader: schema: type: string example: part_123456789 OrgIdHeader: schema: type: string example: org_123456789 schemas: StandardResponse: type: object description: Standard response structure for successful operations properties: ok: type: boolean example: true description: Indicates if the operation was successful data: type: object description: Contains the response data Webhook: type: object description: Webhook information properties: created_at: $ref: '#/components/schemas/Timestamp' description: type: string example: Payment notifications description: Description of the webhook enabled: type: boolean example: true description: Whether the webhook is enabled endpoint: type: string example: https://example.com/webhook description: Endpoint URL of the webhook events: type: array description: List of events the webhook subscribes to items: $ref: '#/components/schemas/WebhookEvent' name: type: string example: Payment Webhook description: Name of the webhook partner_id: type: string example: part_123456789 description: Partner identifier secret: type: string example: whsec_123456789 description: Secret for webhook signature verification token: type: string example: whk_123456789 description: Webhook identifier token updated_at: $ref: '#/components/schemas/Timestamp' ErrorResponse: type: object description: Standard error response structure properties: code: type: string description: Error code identifying the type of error message: type: string description: Human-readable error message Timestamp: type: object description: A timestamp with seconds since epoch properties: seconds: type: number format: int64 example: 1691831179 description: Time in seconds since epoch WebhookEvent: type: object description: Webhook event information properties: created_at: $ref: '#/components/schemas/Timestamp' token: type: string example: evt_123456789 description: Event identifier token record_type: type: string enum: - RT_PaymentSubmissions - RT_Error - RT_Payments - RT_PaymentAdmissions - RT_PaymentAdmissionTasks - RT_Transactions example: RT_PaymentSubmissions description: Type of record for the event event_type: type: string enum: - EK_Created - EK_Updated example: EK_Created description: Type of event updated_at: $ref: '#/components/schemas/Timestamp' webhook_id: type: string example: whk_123456789 description: Webhook identifier securitySchemes: bearerAuth: type: http scheme: bearer ````