Clarify webhook behavior in docs/README

README.md

@@ -34,12 +34,16 @@ docker run -d \
     nginx
 ```
 
-## Example of webhooks usage
-**Webhook config example**
-A webhook is configured using a set of CLI flags. At its most basic only `webhook-url` needs to be set.
+## Webhooks
+Webhooks are executed asynchronously from the main git-sync process. If a `webhook-url` is configured,
+when a change occurs to the local git checkout a call is sent using the method defined in `webhook-method`
+(default to `POST`). git-sync will continually attempt this webhook call until it succeeds (based on `webhook-success-status`).
+If unsuccessful, git-sync will wait `webhook-backoff` (default `3s`) before re-attempting the webhook call.
 
 **Usage**
 
+A webhook is configured using a set of CLI flags. At its most basic only `webhook-url` needs to be set.
+
 ```
 docker run -d \
     -v /tmp/git-data:/git \

cmd/git-sync/main.go

@@ -71,7 +71,7 @@ var flWebhookStatusSuccess = flag.Int("webhook-success-status", envInt("GIT_SYNC
 var flWebhookTimeout = flag.Duration("webhook-timeout", envDuration("GIT_SYNC_WEBHOOK_TIMEOUT", time.Second),
 	"the timeout used when communicating with the webhook target")
 var flWebhookBackoff = flag.Duration("webhook-backoff", envDuration("GIT_SYNC_WEBHOOK_BACKOFF", time.Second*3),
-	"the duration to wait after a failed webhook call")
+	"if a webhook call fails (dependant on webhook-success-status) this defines how much time to wait before retrying the call")
 
 var flUsername = flag.String("username", envString("GIT_SYNC_USERNAME", ""),
 	"the username to use")