{"templateId":"markdown","versions":[{"version":"v1","label":"v1","link":"/api-reference/v1/components/docs/webhooks_overview","default":true,"active":false,"folderId":"1b9c9f54"},{"version":"v2","label":"v2 (Beta)","link":"/api-reference/v2/components/docs/webhooks_overview","default":false,"active":true,"folderId":"1b9c9f54"}],"sharedDataIds":{},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Flute Developer","siteUrl":"https://developer.flute.com","description":"Documentation and API reference for integrating Flute payment processing.","lang":"en-US","llmstxt":{"hide":true,"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Webhooks are notifications that are automatically sent when specific predefined events occur."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Webhooks are commonly used, for instance, when payment processors need to notify a client that a charge succeeded or failed, when a subscription renews, or an incoming SMS message is available."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["They replace polling."," ","This polling might have been:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Software polling for a status change either through a loop, or timed queries."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Manually by a user explicitly polling expecting a response or pending status to be returned."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A merchant can only affect their own webhooks."," ","They cannot view or modify other merchant's webhooks."," ","Likewise, a partner can only affect merchants associated to them."," ","They cannot affect merchants of other partners."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Required API Permissions"]},{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]}," ","Required API Permission: Webhooks"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Webhook Workflows"]},{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]}," ","To create and manage Flute webhooks, use the following procedures and workflows."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Creating Webhooks"]},{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]}," ","1) Optionally, review all the valid event types."," ","Webhooks can accept one or more event types."," ","Each event type is evaluated independently."," ","Selected events are not required to be related and may relate to different transaction types or workflows."," ","For organizational reasons, multiple webhooks can be created."," ","Each webhook can then have its own set of event types."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To list all available events, see ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /v2/webhooks/event-types"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["2) Create the webhook",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]}," ","To create the webhook, see ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /v2/webhooks/endpoints"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["3) Test the webhook",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]}," ","Verify the endpoint is reachable (sends a test ping).",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]}," ","To test the webhook, see ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /v2/webhooks/endpoints/{webhookId}/ping"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Managing Webhooks"]},{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]}," ","The following set of endpoints manage webhooks."]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This endpoint provides a list of all available webhook for the merchant.",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]}," ","To list all the available webhooks, see ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /v2/webhooks/endpoints"]}]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This endpoint retrieves webhook details specified by its webhookId.",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]}," ","To retrieve a specific webhook, see ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /v2/webhooks/endpoints/{webhookId}"]}]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This endpoint provides an ability to update or change a webhook."," ","For example, the set of event types may be changed without having to create a new webhook.",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]}," ","To modify or update a specific webhook, see ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PATCH /v2/webhooks/endpoints/{webhookId}"]}]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This endpoint deletes the specific webhook."," ","This action can neither be undone nor can the webhook be retrieved."," ","This does not erase entries in the log file.",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]}," ","To delete a specific webhook, see ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DELETE /v2/webhooks/endpoints/{webhookId}"]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Monitoring Webhooks"]},{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]}," ","The following set of endpoints monitor webhooks."," ","These may be used to verify success of an attempt or assist in determining the cause of a problem."]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This endpoint lists success level of delivery attempts.",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]}," ","To view webhooks delivery attempts log file, see ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /v2/webhooks/delivery-logs"]}]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This endpoint lists success level of delivery attempts for a specified webhook.",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]}," ","To view a specified webhook delivery attempts log file, see ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /v2/webhooks/delivery-logs/{webhookId}"]}," ","Get full request/response detail for a single attempt"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This endpoint exports the delivery logs file."," ","It may be specified as either a CSV or JSON format.",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]}," ","To export webhooks delivery attempts log file, see ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /v2/webhooks/delivery-logs/export"]}]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This endpoint retries a failed delivery.",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]}," ","To retry a failed delivery, see ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /v2/webhooks/delivery-logs/{id}/retry"]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Client Handling of Messages"]},{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]}," ","The webhook sends a message to the URL specified by the client."," ","This is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["endpointUrl"]}," of ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST {{baseURL}}/v2/webhooks/endpoints"]},"."," ","The message is considered successfully sent after a send confirmation is received."," ","If that send confirmation was not successfully confirmed, the message will be sent, or retried, a number of times before failing."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["After being successfully sent to the receiving endpoint or URL,"," ","it is the client's responsibility to handle it after that."," ","As a best practice, we recommend that the message is first verified to be from Flute."," ","For example, use HMAC verification."," ","This step greatly increases security and reduces system vulnerabilities such as spoofing, tampering, or data injection."," ","The IP address could be blocked to prevent future intrusions."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Once the sender is verified, the client can process the message as they need."," ","For example, code or an application on the receiving server may create an email or SMS message to send to the client."]}]},"headings":[],"frontmatter":{"seo":{"title":""}},"lastModified":"2026-07-10T14:53:12.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/api-reference/v2/components/docs/webhooks_overview","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}