An integration creates a new trust boundary every time one application asks another to act. A webhook endpoint is not trustworthy simply because its URL is obscure, and an API key is not safe merely because a workflow works. Start with a map of the data and permissions involved. Then verify requests, limit privileges and make failures recoverable without leaking secrets.
Know what crosses the boundary
List the sender, receiver, event types and actions for each integration. Note which fields contain personal or confidential information and which application is the source of truth. Identify who owns the connection and who can disable it. This small inventory helps distinguish a harmless notification from a request capable of changing customer records, sending messages or initiating another sensitive operation.
Accept only the methods and content types the endpoint needs. Set reasonable limits on request size and parsing time using the framework or hosting platform. Validate required fields and permitted event types before business logic runs. Use HTTPS and avoid treating a field supplied by the sender as authorization to act on any account. The integration must enforce its own scope, not just trust a convenient identifier.
Verify the signature using the provider’s rules
Use the provider’s supported verification library where possible. Many schemes sign the raw request body, sometimes together with a timestamp. Parsing and reserializing JSON can change the bytes and break verification, so preserve the raw body when the documentation requires it. Use the correct secret for the environment and endpoint. A test webhook secret should not silently become the production configuration.
Reject missing or invalid signatures before doing work. Follow the documented comparison and timestamp-tolerance rules rather than inventing a generic algorithm. A signature can establish authenticity and integrity under that scheme; it does not automatically prevent every replay. Where timestamp checks are supported, enforce them. Where they are not, design deduplication and any additional safeguards around the provider’s actual delivery model.
Make repeated delivery safe
Webhook delivery is often retried, and events can arrive out of order. Persist a provider event identifier with an appropriate uniqueness constraint before applying an irreversible effect. Decide how concurrent deliveries behave and how long deduplication records must remain. If a provider offers no stable identifier, document the limitations of any alternative instead of assuming that a timestamp makes every request unique.
Separate accepting an event from processing a slow task when the platform allows it. Acknowledge according to the provider’s expectations only after the event is safely recorded or handled. Use bounded retries and a review queue for failures that cannot resolve themselves. Never allow a retry loop to send unlimited emails or repeat a destructive action simply because a downstream application was temporarily unavailable.
Give every credential the smallest useful scope
Use separate credentials for development and production, and for different integrations when the provider supports it. Grant only the permissions required for the agreed action. Avoid using a personal administrator key as a shortcut. Record the purpose, owner and rotation process without copying the secret into the inventory. Review access when a project ends, a person leaves or the workflow’s responsibilities change.
Store secrets in server-side environment variables or an appropriate secret manager. Do not place them in client-side bundles, public configuration, source control, screenshots or URLs. In Next.js, a NEXT_PUBLIC_ variable is intended for browser exposure, so it is not a place for an API secret. Redact authorization headers and sensitive request fields in logs before sending diagnostics to another service.
Plan rotation and incident recovery
If a key is exposed, revoke or rotate it promptly through the provider’s supported process. Removing it from the latest commit does not make previous copies safe. Check usage logs, identify the affected scope and investigate whether unauthorized actions occurred. Follow your incident and notification obligations with appropriate professional advice. Do not assume that a lack of visible errors proves the credential was never used.
For planned rotation, use overlapping credentials only if the provider supports that pattern and the risk is acceptable. Deploy the new value, verify the integration and retire the old one. Keep a rollback procedure that does not reintroduce a compromised key. Make the owner and escalation contact easy to find so recovery does not depend on an undocumented connection in someone’s personal account.
Test the controls, not just the happy path
Use a local or isolated test environment with synthetic data. Exercise a valid request, a modified payload, an absent signature, an expired timestamp where applicable and a duplicated event. Check that invalid requests cause no downstream action. Simulate a failed dependency and confirm that recovery is visible. Use the provider’s test tools rather than sending fabricated requests to a live system you do not control.
Review the implementation when the provider, framework or deployment environment changes. Keep the verification rules and operational instructions near the workflow. Security headers, access controls and careful secret handling reduce specific risks, but they are not certifications or guarantees. A reliable integration combines several controls and an honest understanding of what each control does, where it applies and what still needs human review.
Sources & further reading
- OWASP — secrets management cheat sheet
- Stripe — webhook signature verification
- Next.js — environment variables
Practical guidance, not legal advice. Adapt it to your environment.