Creates a webhook endpoint

Request

POST {{baseURL}}/v2/webhooks/endpoints

This endpoint creates a new webhook endpoint.

New endpoints default to Active on creation. Only Active endpoints are eligible for real event dispatch.

See Also:
To list all of available webhooks, see GET /v2/webhooks/endpoints.
To retrieve a specified webhook, see GET /v2/webhooks/endpoints/{{endpointId}}.
To update a webhook, see PATCH /v2/webhooks/endpoints/{{endpointId}}.
To delete a webhook, see DELETE /v2/webhooks/endpoints/{{endpointId}}

Security

Bearer

Bodyapplication/json

endpointNamestring, <= 255 charactersrequired

Specifies the display name for the webhook.

This is a free-formed name that is convenient to recognize.

Example: Peppared Street Cafe's Reconciliation

Example:"Peppared Street Cafe's Reconciliation"

endpointUrlstring, <= 2048 charactersrequired

Specifies the HTTPS callback URL that receives webhook events.

Example: https://example.com/webhooks/pepparedstreetcafe

Example:"https://example.com/webhooks/pepparedstreetcafe"

eventTypesstringrequired

Identifies events that are subscribed to.

Valid values are:

Wire value	Meaning	Group
api_key.created	An API key was created	API Keys (affiliate only)
api_key.deleted	An API key was revoked or deleted	API Keys (affiliate only)
invoice.created	A new invoice was created	Invoices
invoice.paid	An invoice was marked as paid	Invoices
merchant.created	A new merchant account was created	Merchants (affiliate only)
payment_session.completed	A payment session reached a terminal state (completed, failed, or canceled)	Payment Sessions
payment_session.created	A payment session was created	Payment Sessions
quick_payment.created	A quick payment link was created	Quick Payments
quick_payment.paid	A quick payment link was paid	Quick Payments
settlement.batch.completed	A batch settlement was processed and settled	Settlement
subscription.created	A new subscription was created	Subscriptions
subscription.delinquent	A subscription entered a delinquent state after repeated payment failures	Subscriptions
subscription.paid	A subscription payment was successfully collected	Subscriptions
subscription.payment_failed	A subscription payment attempt failed	Subscriptions
terminal.added	A new terminal was registered to the account	Terminals
terminal.deactivated	A terminal was deactivated on the account	Terminals
terminal.out_of_paper	A terminal paper roll is empty	Terminals
transaction.ach.cancelled	An ACH transaction was canceled before processing	ACH Transactions
transaction.ach.charged_back	An ACH transaction was returned or charged back	ACH Transactions
transaction.ach.cleared	An ACH transaction successfully cleared	ACH Transactions
transaction.ach.failed	An ACH transaction failed due to a processing error	ACH Transactions
transaction.ach.held	An ACH transaction was placed on hold for review	ACH Transactions
transaction.ach.in_progress	An ACH transaction was submitted to the network	ACH Transactions
transaction.ach.refunded	An ACH transaction was refunded to the originator	ACH Transactions
transaction.ach.scheduled	An ACH transaction was created and scheduled	ACH Transactions
transaction.card.authorized	A card payment authorization was approved	Card Transactions
transaction.card.captured	An authorized card payment was captured	Card Transactions
transaction.card.declined	A card payment was declined by the issuer	Card Transactions
transaction.card.failed	A card payment failed due to a processing error	Card Transactions
transaction.card.refunded	A card payment was refunded to the cardholder	Card Transactions
transaction.card.voided	A card authorization was voided before capture	Card Transactions

Examples:
null
[ "transaction.card.captured" ]
[ "transaction.card.captured", "transaction.card.authorized" ]

Enum:"api_key.created""api_key.deleted""invoice.created""invoice.paid""merchant.created""payment_session.completed""payment_session.created""quick_payment.created""quick_payment.paid""settlement.batch.completed"

Example:

[
  "transaction.card.captured",
  "transaction.card.refunded",
  "settlement.batch.completed",
  null
]

curl -i -X POST \
  https://sandbox.api.flute.com/v2/webhooks/endpoints \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "endpointName": "Peppared Street Cafe'\''s Reconciliation",
    "endpointUrl": "https://example.com/webhooks/pepparedstreetcafe",
    "eventTypes": [
      "transaction.card.captured",
      "transaction.card.refunded",
      "settlement.batch.completed",
      null
    ]
  }'

Responses

Bodyapplication/json

endpointIdstring, (uuid)

Indicates the webhook endpoint identifier.

Example: 9ab3d9e0-1f2a-4b3c-4d5e-6f7a8b9c0d36

Example:"9ab3d9e0-1f2a-4b3c-4d5e-6f7a8b9c0d36"

endpointNamestring or null, <= 255 characters

Indicates the display name for the webhook.

This is a free-formed name that is convenient to recognize.

Example: Peppared Street Cafe's Reconciliation

Example:"Peppared Street Cafe's Reconciliation"

endpointUrlstring or null, <= 2048 characters

Indicates the HTTPS callback URL that receives webhook events.

Example: https://example.com/webhooks/pepparedstreetcafe

Example:"https://example.com/webhooks/pepparedstreetcafe"

endpointStatusstring or null

Indicates the endpoint status.

Valid values are:

Value	Description
Active	The webhook endpoint is enabled and available for use.
Inactive	The webhook endpoint is disabled and not available for use. It still exists but will not send event notifications. It may be re-activated. In contrast, a deleted webhook has been removed entirely and cannot be re-activated. A new webhook must be created.

Example: Active

Enum:"Active""Inactive"

Example:"Active"

hmacSecretstring or null

Indicates the HMAC signing secret used to verify webhook payloads.

This value is returned only on creation and is never shown again.

eventTypesstring

Identifies events that are subscribed to.

Valid values are:

Wire value	Meaning	Group
api_key.created	An API key was created	API Keys (affiliate only)
api_key.deleted	An API key was revoked or deleted	API Keys (affiliate only)
invoice.created	A new invoice was created	Invoices
invoice.paid	An invoice was marked as paid	Invoices
merchant.created	A new merchant account was created	Merchants (affiliate only)
payment_session.completed	A payment session reached a terminal state (completed, failed, or canceled)	Payment Sessions
payment_session.created	A payment session was created	Payment Sessions
quick_payment.created	A quick payment link was created	Quick Payments
quick_payment.paid	A quick payment link was paid	Quick Payments
settlement.batch.completed	A batch settlement was processed and settled	Settlement
subscription.created	A new subscription was created	Subscriptions
subscription.delinquent	A subscription entered a delinquent state after repeated payment failures	Subscriptions
subscription.paid	A subscription payment was successfully collected	Subscriptions
subscription.payment_failed	A subscription payment attempt failed	Subscriptions
terminal.added	A new terminal was registered to the account	Terminals
terminal.deactivated	A terminal was deactivated on the account	Terminals
terminal.out_of_paper	A terminal paper roll is empty	Terminals
transaction.ach.cancelled	An ACH transaction was canceled before processing	ACH Transactions
transaction.ach.charged_back	An ACH transaction was returned or charged back	ACH Transactions
transaction.ach.cleared	An ACH transaction successfully cleared	ACH Transactions
transaction.ach.failed	An ACH transaction failed due to a processing error	ACH Transactions
transaction.ach.held	An ACH transaction was placed on hold for review	ACH Transactions
transaction.ach.in_progress	An ACH transaction was submitted to the network	ACH Transactions
transaction.ach.refunded	An ACH transaction was refunded to the originator	ACH Transactions
transaction.ach.scheduled	An ACH transaction was created and scheduled	ACH Transactions
transaction.card.authorized	A card payment authorization was approved	Card Transactions
transaction.card.captured	An authorized card payment was captured	Card Transactions
transaction.card.declined	A card payment was declined by the issuer	Card Transactions
transaction.card.failed	A card payment failed due to a processing error	Card Transactions
transaction.card.refunded	A card payment was refunded to the cardholder	Card Transactions
transaction.card.voided	A card authorization was voided before capture	Card Transactions

Examples:
null
[ "transaction.card.captured" ]
[ "transaction.card.captured", "transaction.card.authorized" ]

Example:

[
  "transaction.card.captured",
  "transaction.card.refunded",
  "settlement.batch.completed",
  null
]

createdOnstring, (date-time)

Indicates the date-time (in an ISO 8601 UTC date-time format) the webhook was created on.

Example: 2026-01-15T10:30:56.264Z

Example:"2026-01-15T10:30:56.264Z"

Response

{
  "endpointId": "1e3fd30d-5fc2-4a69-9ea6-d0dcf05ab5ce",
  "endpointName": "Peppared Street Cafe's Reconciliation",
  "endpointUrl": "https://example.com/webhooks/pepparedstreetcafe",
  "endpointStatus": "Active",
  "hmacSecret": "7b3e9a1f4c8d2056e1a9b7c3f5d80426a9c1e3b5d7f9024680ace13579bdf024",
  "eventTypes": [
    "transaction.card.captured",
    "transaction.card.refunded",
    "settlement.batch.completed"
  ],
  "createdOn": "2026-05-05T14:30:00Z"
}