Webhooks

A webhook sends selected FSRevs activity to another service as it happens. Use one when an automation needs to respond to a completed Form, new Customer, Review response, or other supported activity.

If you use Make or Zapier, start with the native FSRevs Make app or FSRevs Zapier app. Each app creates and manages the webhooks behind its triggers. Create a webhook yourself when you are connecting another service or building a custom integration.

Understand who manages a webhook

A webhook you create in the FSRevs Portal is customer-managed. You can edit its activity and scope, replace its URL, rotate its signing secret, send a test, disable it, and re-enable it from FSRevs.

A webhook created by Zapier, Make, or another connected app is managed by that app. FSRevs shows its activity, scope, status, connection context, and delivery history, and provides Stop Deliveries as an emergency control. To test, change, or recreate its trigger, return to the connected app. FSRevs does not expose portal editing, secret replacement, Test Delivery, or normal re-enabling for a connected-app webhook because those changes could put the two systems out of sync.

After stopping a connected-app webhook, reconnect or recreate the trigger in Zapier or Make. Activity that occurs while the trigger is disconnected is not automatically replayed.

Create a webhook

1. Get the production Webhook URL from the service that will receive messages.
2. In FSRevs, open Integrations → Webhooks and choose Create Webhook.
3. Choose a Webhook owner. The owner’s current FSRevs permissions determine what may be sent.
4. Choose the activity, Forms, and Review Flows to include.
5. Leave Include sensitive event details off unless a trusted service needs Customer context, Form answers, or written feedback.
6. Create the webhook and immediately copy its one-time signing secret.
7. Open the webhook, choose Send Test, and confirm that the receiving service accepts the message.

The owner must have API Access enabled, but webhook delivery does not use an API credential. FSRevs sends directly to the Webhook URL, and the receiving service uses the separate signing secret to verify each message.

The Webhook URL must be a public HTTPS address. FSRevs does not accept redirects, embedded usernames or passwords, IP-address URLs, or private-network destinations.

Choose what activity to send

The webhook can send activity when:

• A Custom Form is completed.
• A Customer is created or changed.
• A Review Request is sent or prepared on a team member’s device.
• A Review Request receives its first completed response.
• Written Review feedback is recorded.
• A customer continues to a Review destination.

Choose All to include current and future Forms or Review Flows. Choose Selected to limit the webhook to particular items.

To react only to a particular rating, answer, Customer, or employee, add that condition in the receiving automation. FSRevs webhook scope selects event types and Forms or Review Flows; it does not filter messages by individual answer or rating values.

Review Request sent or prepared records queued FSRevs delivery or preparation in a team member’s app. It does not prove the message arrived. A Review destination visit records a handoff to a review site, not a confirmed posted review.

New subscriptions receive future activity. Reattaching a webhook or expanding its scope does not replay activity whose delivery recipients have already been determined. Delayed processing excludes subscriptions created after the activity was recorded.

Selecting an item does not give the webhook owner access to it. FSRevs checks the owner’s current access before sending each message. If access is removed, future activity from that item stops sending, and messages skipped while access was unavailable are not sent later.

Disabled or deleted items remain selected in case they are restored. Permanently deleted items can be removed with Clean up deleted selections. If every selected item has been permanently deleted, edit the webhook and choose replacements or switch that section to All.

Decide whether to include sensitive details

The default message is intentionally limited. It identifies what happened and the related FSRevs records without including Customer contact details, Form answers, upload information, or written Review feedback.

Turn on Include sensitive event details only when a trusted receiving service needs supported details such as:

• Customer and recipient context
• Processed Custom Form answers and safe upload information
• Written Review feedback
• Creator, sender, or employee names

Detailed webhook messages never include uploaded file contents, download links, staff contact details, credentials, permissions, or browser audit information. Customer-created and Customer-updated messages remain limited; a technical integration can retrieve the current Customer through the authenticated API when needed.

Changing this setting affects future messages only.

Save and verify your signing secret

The signing secret is a private value shared between FSRevs and the service receiving the webhook. It is not an API credential. The receiver uses it to confirm that a message came from FSRevs and was not changed in transit.

For a customer-managed webhook, FSRevs shows the signing secret once when the webhook is created, when its secret is rotated, or when its Webhook URL is replaced. It cannot be retrieved later through the Portal. If it is lost or exposed, rotate it and update the receiving service immediately. Connected apps manage their own trigger secrets and setup outside the Portal.

Give the secret only to the trusted person or service responsible for verification. Messages can reach a receiver that does not verify them, but that receiver cannot confirm their source or integrity.

Send a test and review delivery health

For a customer-managed webhook, use Send Test from the webhook detail page. It sends a real signed test message without Customer data. A successful test confirms that FSRevs can reach the service and that the service accepts the message. Test connected-app triggers in Zapier or Make instead.

The test does not change production delivery history or webhook health. For production messages, use the detail page to review pending or failed deliveries and each recorded attempt. After fixing the receiving service, you can deliberately try a failed delivery again.

FSRevs may try a temporary webhook failure again, so the same activity can arrive more than once. Configure the receiving service to recognize repeated activity instead of running the automation twice.

After fixing the receiving service, a manual redelivery makes one deliberate attempt. It does not restart the automatic retry schedule.

If one webhook produces an unusually rapid loop of Customer updates, FSRevs may disable that webhook and notify its owner. Review the connected automation before turning it back on.

Troubleshooting

The webhook cannot be created

Confirm that the owner still has API Access and that the Webhook URL is a public HTTPS address. Then verify that you can access every selected Form or Review Flow.

A Form or Review Flow is missing

The webhook owner may not currently have access to it. Choices follow the owner’s Location scope.

Messages stopped after a permission change

The webhook cannot send activity that its owner can no longer access. Restore the appropriate access for future activity or choose another eligible owner.

A service processed the same activity twice

Ask your technical partner to confirm that the service stores and checks each Event ID before processing a message.

The signing secret was lost or exposed

For a customer-managed webhook, rotate the secret from the webhook detail page and update the receiving service before relying on future messages. For a connected-app webhook, reconnect or recreate the trigger in its owning app.

The test succeeds but no real activity arrives

Create a new event after the subscription is connected. Confirm the event type, selected Form or Review Flow, and owner’s current access. A test has no Customer data and does not prove that a real event matches the subscription.

For your technical partner

Verify each message

Keep the raw request body available. Build the signature input from the decimal Unix timestamp, a period, and the exact raw body:

decimal_unix_timestamp + "." + raw_request_body

For every message:

1. Read X-FSRevs-Timestamp and reject messages outside the age your integration accepts.
2. Compute HMAC-SHA256 over the signature input using the signing secret.
3. Encode the result as lowercase hexadecimal and prefix it with v1=.
4. Compare it with X-FSRevs-Signature using a timing-safe comparison.
5. Read the Event ID from the verified message body and use it to ignore duplicates. If you use X-FSRevs-Event-Id, check that it matches the signed body; the header alone is not proof of identity.

Do not parse and reserialize the JSON before checking the signature: changes to whitespace or escaping change the signed bytes. Reject timestamps unreasonably far in the future as well as messages older than your receiver accepts.

Trusted adapter delivery resolution

An approved native adapter that cannot access the untouched request bytes may use POST /api/v1/webhook-deliveries/resolve instead of attempting to recreate the signed JSON. The endpoint accepts the delivery proof plus X-FSRevs-Subscription-Id lookup metadata, reconstructs the retained payload inside FSRevs, verifies the existing HMAC, and rechecks the current credential, subscription scope, and resource access before returning data.

The subscription header is not part of the signature and is never trusted by itself. Resolution requires the current API credential that created the subscription and works only while the delivery proof records are retained. Custom webhook receivers that have raw-body access should continue to verify the signature directly as described above.

Event and retry contract

Public webhook messages use schema version 1. The supported event types are custom_form.completed, customer.created, customer.updated, review_request.sent, review_response.completed, review_feedback.recorded, and review_destination.visited.

Every message reports details_included and details_prepared_at. occurred_at identifies when the immutable activity occurred. When sensitive details are included, details_prepared_at identifies when those values were prepared; it is null for a lean message. An adapter’s separately returned resource is the current resource that its connection is still authorized to read, not a historical snapshot.

Automatic retry and manual redelivery preserve the Event ID and exact JSON body. FSRevs makes the initial attempt and up to seven automatic retries after approximately 1 minute, 5 minutes, 15 minutes, 1 hour, 3 hours, 6 hours, and 12 hours. A valid Retry-After response may delay an attempt further, up to the 12-hour bound.

Each attempt receives a fresh timestamp and signature. Deduplicate by Event ID, not by signature or delivery time. Acknowledge a verified message promptly after safely accepting it for processing; keep slow downstream work separate from webhook receipt.

Manage webhooks through the API

An API credential with the required permissions can create, list, inspect, and disable webhooks. Creation requires an Idempotency-Key. Replaying creation can return the signing secret only while the current credential still has webhook-management permission and permission to read every subscribed event type.

Webhooks created with an API credential are connected-app-managed in the Portal. They remain visible with delivery history and an emergency Stop Deliveries action, but normal editing, re-enabling, secret or URL replacement, and Test Delivery remain with the application that created them. Customer-managed webhooks retain those Portal operations.

See the generated API reference for exact event fields, sensitive-detail coverage, permissions, request and response schemas, limits, and errors.