OpenAPI Specification
openapi: 3.1.0
info:
title: Method Account Attributes Webhooks API
version: '2025-12-01'
license:
name: Proprietary
url: https://methodfi.com
description: "The Method API enables you to retrieve financial data, create payments, and manage\nentities and accounts programmatically. This specification covers the public API\nsurface for version `2025-12-01`.\n\n## Authentication\n\nMost API requests require a Bearer token in the `Authorization` header.\nUse your secret key (`sk_...`) for server-side requests and public key (`pk_...`)\nfor client-side Element requests. Public Message-Level Encryption key discovery\nendpoints are documented separately and do not require authentication.\n\n## Versioning\n\nThe API version is selected via the `Method-Version` header. This spec targets\nversion `2025-12-01`. The SDK sets this header automatically.\n\n## Response Envelope\n\nMost JSON responses are wrapped in a standard envelope:\n\n```json\n{\n \"success\": true,\n \"data\": { ... },\n \"message\": null\n}\n```\n\nThe `/.well-known/jwks.json` endpoint is an exception and returns a bare JWK set.\n\n## Pagination\n\nList endpoints return pagination metadata in response headers:\n`Pagination-Page`, `Pagination-Page-Count`, `Pagination-Page-Limit`,\n`Pagination-Total-Count`, `Pagination-Page-Cursor-Prev`, `Pagination-Page-Cursor-Next`.\n\n## Expandable Fields\n\nCertain resource fields can be expanded from IDs to full objects using the\n`expand` query parameter. Maximum nesting depth is 4 levels.\n"
contact:
name: Method Financial
url: https://methodfi.com
email: team@methodfi.com
servers:
- url: https://production.methodfi.com
description: Production
- url: https://sandbox.methodfi.com
description: Sandbox
- url: https://dev.methodfi.com
description: Development
security:
- SecretKey: []
tags:
- name: Webhooks
description: Webhook subscriptions
paths:
/webhooks:
get:
operationId: listWebhooks
summary: List all webhooks
description: Returns all active and requires-attention webhooks for the authenticated team.
tags:
- Webhooks
security:
- SecretKey: []
parameters:
- $ref: '#/components/parameters/method_version'
responses:
'200':
description: A list of webhooks.
content:
application/json:
schema:
$ref: '#/components/schemas/WebhookListResponse'
example:
success: true
data:
- id: whk_cSGjA6d9N8y8v
type: payment.update
url: https://example.com/webhooks
status: active
expand_event: true
error: null
metadata:
environment: production
created_at: '2026-01-15T18:30:00.000Z'
updated_at: '2026-01-15T18:30:00.000Z'
message: null
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'429':
$ref: '#/components/responses/RateLimited'
'500':
$ref: '#/components/responses/InternalError'
post:
operationId: createWebhook
summary: Create a webhook
description: Creates a new webhook subscription for the specified event type.
tags:
- Webhooks
security:
- SecretKey: []
parameters:
- $ref: '#/components/parameters/method_version'
- $ref: '#/components/parameters/idempotency_key'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/WebhookCreateRequest'
example:
type: payment.update
url: https://example.com/webhooks
auth_token: webhook-basic-token
hmac_secret: webhook-signing-secret
expand_event: true
metadata:
environment: production
responses:
'200':
description: The created webhook.
content:
application/json:
schema:
$ref: '#/components/schemas/WebhookResponse'
example:
success: true
data:
id: whk_cSGjA6d9N8y8v
type: payment.update
url: https://example.com/webhooks
status: active
expand_event: true
error: null
metadata:
environment: production
created_at: '2026-01-15T18:30:00.000Z'
updated_at: '2026-01-15T18:30:00.000Z'
message: null
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'422':
$ref: '#/components/responses/UnprocessableEntity'
'429':
$ref: '#/components/responses/RateLimited'
'500':
$ref: '#/components/responses/InternalError'
callbacks:
webhookEvent:
'{$request.body#/url}':
post:
summary: Webhook event delivery
description: Method will POST this payload to your webhook URL when a subscribed event occurs.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/WebhookEventPayload'
responses:
'200':
description: Webhook received successfully.
/webhooks/{webhookId}:
get:
operationId: retrieveWebhook
summary: Retrieve a webhook
description: Returns a single webhook by its identifier.
tags:
- Webhooks
security:
- SecretKey: []
parameters:
- $ref: '#/components/parameters/method_version'
- $ref: '#/components/parameters/WebhookIdParam'
responses:
'200':
description: The requested webhook.
content:
application/json:
schema:
$ref: '#/components/schemas/WebhookResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/RateLimited'
'500':
$ref: '#/components/responses/InternalError'
patch:
operationId: updateWebhook
summary: Update a webhook status
description: Updates an existing webhook's status.
tags:
- Webhooks
security:
- SecretKey: []
parameters:
- $ref: '#/components/parameters/method_version'
- $ref: '#/components/parameters/WebhookIdParam'
- $ref: '#/components/parameters/idempotency_key'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/WebhookUpdateRequest'
example:
status: disabled
responses:
'200':
description: The updated webhook.
content:
application/json:
schema:
$ref: '#/components/schemas/WebhookResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'422':
$ref: '#/components/responses/UnprocessableEntity'
'429':
$ref: '#/components/responses/RateLimited'
'500':
$ref: '#/components/responses/InternalError'
delete:
operationId: deleteWebhook
summary: Delete a webhook
description: Deletes a webhook subscription.
tags:
- Webhooks
security:
- SecretKey: []
parameters:
- $ref: '#/components/parameters/method_version'
- $ref: '#/components/parameters/WebhookIdParam'
- $ref: '#/components/parameters/idempotency_key'
responses:
'200':
description: The deleted webhook.
content:
application/json:
schema:
$ref: '#/components/schemas/WebhookDeleteResponse'
example:
success: true
data: null
message: null
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'422':
$ref: '#/components/responses/UnprocessableEntity'
'429':
$ref: '#/components/responses/RateLimited'
'500':
$ref: '#/components/responses/InternalError'
components:
schemas:
ErrorObject:
type: object
required:
- type
- code
- message
properties:
type:
type: string
description: Error type category.
enum:
- invalid_request
- api_error
- resource_error
code:
type: integer
description: Numeric error code. Common codes include 400 (bad request), 401 (unauthorized), 403 (forbidden), 404 (not found), 422 (unprocessable entity), 429 (rate limited), and 500 (internal error).
sub_type:
type:
- string
- 'null'
description: More specific error classification.
message:
type: string
description: Human-readable error description.
Webhook:
type: object
required:
- id
- type
- url
- status
- expand_event
- created_at
- updated_at
properties:
id:
type: string
description: Unique identifier for the webhook.
example: whk_cSGjA6d9N8y8v
type:
$ref: '#/components/schemas/WebhookType'
url:
type: string
format: uri
description: URL to receive webhook events.
example: https://example.com/webhooks
status:
$ref: '#/components/schemas/WebhookStatus'
expand_event:
type: boolean
description: Whether to include the full resource data in the webhook payload.
error:
$ref: '#/components/schemas/WebhookResourceError'
metadata:
$ref: '#/components/schemas/Metadata'
created_at:
type: string
format: date-time
description: Timestamp when the webhook was created.
updated_at:
type: string
format: date-time
description: Timestamp when the webhook was last updated.
WebhookStatus:
type: string
enum:
- active
- requires_attention
- disabled
- deleted
WebhookListResponse:
allOf:
- $ref: '#/components/schemas/ListEnvelope'
- type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Webhook'
WebhookResourceError:
type:
- object
- 'null'
description: Error details when a webhook is disabled or requires attention.
required:
- type
- code
- sub_type
- message
properties:
type:
type: string
description: The category of webhook error.
enum:
- WEBHOOK_DISABLED
- WEBHOOK_REQUIRES_ATTENTION
code:
type: integer
description: Numeric error code (25XXX range).
enum:
- 25001
- 25002
- 25003
- 25004
- 25005
- 25006
- 25007
- 25008
- 25009
sub_type:
type: string
description: Specific webhook error classification.
enum:
- WEBHOOK_DISABLED_FAILED_OTHER
- WEBHOOK_DISABLED_RECEIVED_4XX_ERROR
- WEBHOOK_DISABLED_RECEIVED_5XX_ERROR
- WEBHOOK_DISABLED_TIMEOUT_ON_RESPONSE
- WEBHOOK_DISABLED_BY_USER
- WEBHOOK_REQUIRES_ATTENTION_FAILED_OTHER
- WEBHOOK_REQUIRES_ATTENTION_RECEIVED_4XX_ERROR
- WEBHOOK_REQUIRES_ATTENTION_RECEIVED_5XX_ERROR
- WEBHOOK_REQUIRES_ATTENTION_TIMEOUT_ON_RESPONSE
message:
type: string
description: Human-readable error description.
example:
type: WEBHOOK_DISABLED
code: 25002
sub_type: WEBHOOK_DISABLED_RECEIVED_4XX_ERROR
message: Webhook failed 25 times with a client error (4XX type).
WebhookType:
type: string
description: The event type this webhook subscribes to.
enum:
- payment.create
- payment.update
- account.create
- account.update
- account.opened
- account.closed
- account.balance_increased
- account.balance_decreased
- account.credit_limit_increased
- account.credit_limit_decreased
- account.number.update
- entity.create
- entity.update
- entity.new_accounts_pending_consent
- account_verification.create
- account_verification.update
- entity_verification_session.create
- entity_verification_session.update
- payment_reversal.create
- payment_reversal.update
- connection.create
- connection.update
- connect.create
- connect.available
- connect.update
- manual_connect.create
- manual_connect.update
- report.create
- report.update
- product.create
- product.update
- subscription.create
- subscription.update
- credit_score.create
- credit_score.update
- credit_score.available
- credit_score.increased
- credit_score.decreased
- payoff.create
- payoff.update
- balance.create
- balance.update
- identity.create
- identity.update
- account_verification_session.create
- account_verification_session.update
- card_brand.create
- card_brand.available
- card_brand.update
- payment_instrument.create
- payment_instrument.update
- sensitive.create
- sensitive.update
- update.create
- update.update
- attribute.create
- attribute.update
- entity_attribute.create
- entity_attribute.update
- account_attribute.create
- account_attribute.update
- transaction.create
- transaction.update
- entity_vehicle.create
- entity_vehicle.update
- method_jwk.create
- method_jwk.update
- attribute.credit_health_credit_card_usage.increased
- attribute.credit_health_credit_card_usage.decreased
- attribute.credit_health_derogatory_marks.increased
- attribute.credit_health_derogatory_marks.decreased
- attribute.credit_health_hard_inquiries.increased
- attribute.credit_health_hard_inquiries.decreased
- attribute.credit_health_total_accounts.increased
- attribute.credit_health_total_accounts.decreased
- attribute.credit_health_credit_age.increased
- attribute.credit_health_credit_age.decreased
- attribute.credit_health_payment_history.increased
- attribute.credit_health_payment_history.decreased
- attribute.credit_health_open_accounts.increased
- attribute.credit_health_open_accounts.decreased
- entity_attribute.credit_health_open_accounts_value.decreased
- entity_attribute.credit_health_open_accounts_value.increased
- entity_attribute.credit_health_total_accounts_value.decreased
- entity_attribute.credit_health_total_accounts_value.increased
- entity_attribute.credit_health_credit_card_usage_value.decreased
- entity_attribute.credit_health_credit_card_usage_value.increased
- entity_attribute.credit_health_soft_inquiries_value.decreased
- entity_attribute.credit_health_soft_inquiries_value.increased
- entity_attribute.credit_health_hard_inquiries_value.decreased
- entity_attribute.credit_health_hard_inquiries_value.increased
WebhookDeleteResponse:
allOf:
- $ref: '#/components/schemas/SuccessEnvelope'
- type: object
properties:
data:
type:
- object
- 'null'
example: null
WebhookResponse:
allOf:
- $ref: '#/components/schemas/SuccessEnvelope'
- type: object
properties:
data:
$ref: '#/components/schemas/Webhook'
WebhookEventPayload:
type: object
description: The outbound payload delivered to a webhook subscription URL when an event occurs.
required:
- webhook_id
- id
- type
- op
- event
- refs
properties:
webhook_id:
type:
- string
- 'null'
description: The unique identifier of the webhook subscription that triggered this event.
example: whk_cSGjA6d9N8y8R
id:
type:
- string
- 'null'
description: The identifier of the resource modified.
example: acc_BcRdHNjb9TYKV
type:
description: The webhook event type.
example: account.update
oneOf:
- $ref: '#/components/schemas/WebhookType'
- type: 'null'
op:
type:
- string
- 'null'
description: The operation type derived from the event type (the segment after the first dot).
example: update
path:
type:
- string
- 'null'
description: The URL path pointing to the affected resource. Make a HTTP GET request to this path to retrieve the resource. Only present when available.
example: /accounts/acc_BcRdHNjb9TYKV
event:
type:
- string
- 'null'
description: The unique identifier of the event record. Can be used to retrieve the full event details via the Events API.
example: evt_knqJgxKUnqDVJ
refs:
description: An object containing reference IDs to related resources. Commonly includes entity and may include other resource references depending on the event type.
oneOf:
- type: object
additionalProperties:
type: string
- type: 'null'
example:
account: acc_BcRdHNjb9TYKV
entity: ent_qKNBB68bfHGNA
example:
webhook_id: whk_cSGjA6d9N8y8R
id: acc_BcRdHNjb9TYKV
type: account.update
op: update
path: /accounts/acc_BcRdHNjb9TYKV
event: evt_knqJgxKUnqDVJ
refs:
account: acc_BcRdHNjb9TYKV
entity: ent_qKNBB68bfHGNA
Metadata:
type:
- object
- 'null'
additionalProperties: true
description: Arbitrary key-value metadata attached to the resource.
ErrorEnvelope:
type: object
required:
- success
- data
- message
properties:
success:
type: boolean
description: Always `false` for error responses.
data:
type: object
required:
- error
properties:
error:
$ref: '#/components/schemas/ErrorObject'
message:
type: string
ListEnvelope:
type: object
description: Standard envelope for successful responses that return a list payload.
required:
- success
- data
- message
properties:
success:
type: boolean
description: Always `true` for successful responses.
data:
description: Operation-specific list payload.
message:
type:
- string
- 'null'
example:
success: true
data: []
message: null
WebhookUpdateRequest:
type: object
required:
- status
properties:
status:
$ref: '#/components/schemas/WebhookStatus'
WebhookCreateRequest:
type: object
required:
- type
- url
properties:
type:
$ref: '#/components/schemas/WebhookType'
url:
type: string
format: uri
description: URL to receive webhook events.
auth_token:
type: string
description: Authentication token to include in outbound webhook request headers. This value is write-only.
writeOnly: true
hmac_secret:
type: string
description: HMAC secret used to sign outbound webhook deliveries. This value is write-only.
writeOnly: true
expand_event:
type: boolean
description: Whether to include the full resource data in the webhook payload.
metadata:
$ref: '#/components/schemas/Metadata'
SuccessEnvelope:
type: object
description: Standard envelope for successful responses that return a single payload.
required:
- success
- data
- message
properties:
success:
type: boolean
description: Always `true` for successful responses.
data:
description: Operation-specific response payload.
message:
type:
- string
- 'null'
example:
success: true
data: {}
message: null
responses:
RateLimited:
description: Too many requests - rate limit exceeded.
headers:
Retry-After:
description: Number of seconds to wait before retrying.
schema:
type: integer
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
NotFound:
description: Not found - the requested resource does not exist.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
UnprocessableEntity:
description: Unprocessable entity - the request was valid JSON but failed business or validation rules.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
Forbidden:
description: Forbidden - insufficient permissions for this operation.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
Unauthorized:
description: Unauthorized - missing or invalid authentication token.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
BadRequest:
description: Bad request - invalid parameters or request body.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
InternalError:
description: Internal server error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
parameters:
WebhookIdParam:
name: webhookId
in: path
required: true
description: Unique identifier for the webhook.
schema:
type: string
pattern: ^whk_\w+$
method_version:
name: Method-Version
in: header
required: true
description: 'API version to use for this request. This spec targets `2025-12-01`.
The SDK sets this header automatically.
'
schema:
type: string
enum:
- '2025-12-01'
default: '2025-12-01'
idempotency_key:
name: Idempotency-Key
in: header
required: false
description: 'Idempotency key for safely retrying a write request. Reuse the same value when
retrying the same logical operation to avoid creating duplicate side effects.
'
schema:
type: string
format: uuid
securitySchemes:
OpalToken:
type: http
scheme: bearer
description: 'Opal token authentication for Opal session endpoints. Use an Opal token (`otkn_...`)
as the Bearer token. Created via POST /opal/token using a secret key.
'
SecretKey:
type: http
scheme: bearer
description: 'Secret key authentication. Use your team''s secret key (`sk_...`) as the Bearer token.
All authenticated API endpoints require this scheme unless otherwise noted.
'