Webhooks are notifications that are automatically sent when specific predefined events occur.

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.

They replace polling. This polling might have been:

• Software polling for a status change either through a loop, or timed queries.
• Manually by a user explicitly polling expecting a response or pending status to be returned.

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.

Required API Permissions
Required API Permission: Webhooks

Webhook Workflows
To create and manage Flute webhooks, use the following procedures and workflows.

Creating Webhooks
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.

To list all available events, see GET /v2/webhooks/event-types

2) Create the webhook
To create the webhook, see POST /v2/webhooks/endpoints

3) Test the webhook
Verify the endpoint is reachable (sends a test ping).
To test the webhook, see POST /v2/webhooks/endpoints/{webhookId}/ping

Managing Webhooks
The following set of endpoints manage webhooks.

• This endpoint provides a list of all available webhook for the merchant.
  To list all the available webhooks, see GET /v2/webhooks/endpoints

• This endpoint retrieves webhook details specified by its webhookId.
  To retrieve a specific webhook, see GET /v2/webhooks/endpoints/{webhookId}

• 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.
  To modify or update a specific webhook, see PATCH /v2/webhooks/endpoints/{webhookId}

• 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.
  To delete a specific webhook, see DELETE /v2/webhooks/endpoints/{webhookId}

Monitoring Webhooks
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.

• This endpoint lists success level of delivery attempts.
  To view webhooks delivery attempts log file, see GET /v2/webhooks/delivery-logs

• This endpoint lists success level of delivery attempts for a specified webhook.
  To view a specified webhook delivery attempts log file, see GET /v2/webhooks/delivery-logs/{webhookId} Get full request/response detail for a single attempt

• This endpoint exports the delivery logs file. It may be specified as either a CSV or JSON format.
  To export webhooks delivery attempts log file, see GET /v2/webhooks/delivery-logs/export

• This endpoint retries a failed delivery.
  To retry a failed delivery, see POST /v2/webhooks/delivery-logs/{id}/retry

Client Handling of Messages
The webhook sends a message to the URL specified by the client. This is endpointUrl of 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.

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.

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.