# Webhooks

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.

 - [GET /v2/webhooks/endpoints](https://developer.flute.com/api-reference/v2/webhooks/flute-v2-get-webhooks-endpoints.md): GET {{baseURL}}/v2/webhooks/endpoints This endpoint lists all webhook endpoints. The endpoints are for both active and inactive webhooks. This endpoint does not require a specific API token. Either a
 - [POST /v2/webhooks/endpoints](https://developer.flute.com/api-reference/v2/webhooks/flute-v2-post-webhooks-endpoints.md): 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. This e
 - [GET /v2/webhooks/endpoints/{endpointId}](https://developer.flute.com/api-reference/v2/webhooks/flute-v2-get-webhooks-endpoints-endpointid.md): GET {{baseURL}}/v2/webhooks/endpoints/{{endpointId}} This endpoint retrieves a webhook endpoint by ID. This endpoint does not require a specific API token. Either a merchant or partner API token can b
 - [PATCH /v2/webhooks/endpoints/{endpointId}](https://developer.flute.com/api-reference/v2/webhooks/flute-v2-patch-webhooks-endpoints-endpointid.md): PATCH {{baseURL}}/v2/webhooks/endpoints/{{endpointId}} This endpoint updates a webhook endpoint. This endpoint does not require a specific API token. Either a merchant or partner API token can be used
 - [DELETE /v2/webhooks/endpoints/{endpointId}](https://developer.flute.com/api-reference/v2/webhooks/flute-v2-delete-webhooks-endpoints-endpointid.md): DELETE {{baseURL}}/v2/webhooks/endpoints/{{endpointId}} This endpoint deletes a webhook endpoint. All outstanding pending and scheduled retries for this specified webhook are canceled. References in l
 - [POST /v2/webhooks/endpoints/{endpointId}/ping](https://developer.flute.com/api-reference/v2/webhooks/flute-v2-post-webhooks-endpoints-endpointid-ping.md): GET {{baseURL}}/v2/webhooks/endpoints/{{endpointId}}/ping This endpoint validates connectivity to the registered endpoint URL. This endpoint does not require a specific API token. Either a merchant or
 - [GET /v2/webhooks/event-types](https://developer.flute.com/api-reference/v2/webhooks/flute-v2-get-webhooks-event-types.md): GET {{baseURL}}/v2/webhooks/event-types This endpoint lists available webhook event types. The list of available webhook event types are provided by Flute. These are the only events types available to
 - [GET /v2/webhooks/delivery-logs](https://developer.flute.com/api-reference/v2/webhooks/flute-v2-get-webhooks-delivery-logs.md): GET {{baseURL}}/v2/webhooks/delivery-logs This endpoint lists webhook delivery logs for the merchant account. Results are returned in pages of `pageSize` items, with a default of 20 and a maximum of 1
 - [GET /v2/webhooks/delivery-logs/{deliveryLogId}](https://developer.flute.com/api-reference/v2/webhooks/flute-v2-get-webhooks-delivery-logs-deliverylogid.md): GET {{baseURL}}/v2/webhooks/delivery-logs/{{deliveryLogId}} This endpoint retrieves a delivery log by ID. This endpoint does not require a specific API token. Either a merchant or partner API token ca
 - [GET /v2/webhooks/delivery-logs/export](https://developer.flute.com/api-reference/v2/webhooks/flute-v2-get-webhooks-delivery-logs-export.md): GET {{baseURL}}/v2/webhooks/delivery-logs/export This endpoint exports webhook delivery logs as a CSV or JSON file. Query parameters may be combined to filter the exported results. This endpoint does
 - [POST /v2/webhooks/delivery-logs/{deliveryLogId}/retry](https://developer.flute.com/api-reference/v2/webhooks/flute-v2-post-webhooks-delivery-logs-deliverylogid-retry.md): POST {{baseURL}}/v2/webhooks/delivery-logs/{{endpointId}}/retry This endpoint manually retries a failed webhook delivery. This is a single try each time. It does not automatically retry multiple times