A webhook signing secret is a credential, not a setup detail. Send it the way you would send a password: confirm who is receiving it, hand it over through a channel that keeps no copies, and make sure it ends up in a secrets store rather than a ticket. The short version is a one-time secret link sent to a verified contact, with the setup instructions sent separately.
The rest of this guide covers the choice of channel, the checks before you send, what the client should do with the value, and how to handle rotation and troubleshooting without ever pasting the secret again.
Which channel should carry the secret?
Pick the channel by two tests: can you confirm who is able to open it, and how many copies does it leave behind? Email and chat fail the second test, because every message is retained, synced and exported long after the handoff is done.
| Method | What it gives you | Check before sending | | --- | --- | --- | | Authenticated client portal | Named-user access you can revoke | The account belongs to the right contact | | One-time secret link | Destroyed after one open, nothing left in the message | The address you are sending it to, checked separately | | Encrypted messaging | Protected in transit | Who else can open that conversation |
A client portal with individual logins is a good first choice when one exists. Grant access to a named person, not a shared project thread, and remove it once the handoff is complete.
A one-time link keeps the credential out of the email or chat message you use to coordinate. With LinkPilot the secret is encrypted in your browser before it is stored, the stored copy is destroyed after one open, and you can set the link to expire after an hour, a day or a week. Pro plans add a passphrase that you pass on through a separate channel. These controls limit the handoff. They do not replace checking that the right person is on the other end.
Encrypted messaging is the fallback when neither of the above is practical. Encryption in transit does not fix a misaddressed message or an over-shared group, so the recipient check matters even more.
Whatever you choose, keep plain-text email and chat for coordination only. Even services that encrypt in transit keep retention, backups and account access out of your hands.
Verify the client and the recipient
A secure channel does nothing if the secret goes to the wrong inbox. Before you send, confirm that the person asking is responsible for the integration, and that the route you plan to use is actually theirs.
- Confirm identity through a known record. Use a trusted contact entry, an existing business relationship or the client's established process. A new requester, a sudden change of contact or unusual urgency deserves an independent check.
- Read the address character by character, especially when you copy it from a ticket or a recent message. Similar names and shared inboxes are where mistakes happen.
- Review who else has access. Before sharing through a portal or workspace, look at its member list and trim anyone who does not need the credential.
- Confirm delivery on a second channel. If the link went by email, ask on a known phone number or the usual project channel whether access worked. Do not include the secret in that message.
Share the secret with the one person who will configure the endpoint, and let them put it into the client's own secret store. If several engineers need it, that store's access controls are the right place to manage who sees it, not separate copies to each of them.
Prepare the secret before the handoff
Decide what the credential belongs to, where the client should keep it, and how long the handoff should stay open. That preparation makes later rotation and troubleshooting far less confusing.
- One secret per client or endpoint. Reuse means one exposure reaches every integration that shares the value, and rotating one client disrupts all of them. Keep an internal record of which endpoint each secret belongs to, without duplicating the value in project notes.
- Store your own copy in a secrets manager. Not in a local text file, a ticket or a shared document. The same discipline applies to sharing API keys: limit who can reach the credential and keep the handoff short-lived.
- Set a retrieval window. Give the client enough time to pick the value up and finish the setup, and no longer. A link that burns after one open and expires in a day covers most handoffs; if the window passes, create a new one rather than reopening the old.
- Send setup instructions separately. The endpoint URL, the signature header and the verification steps belong in the client's documentation or the project channel. Keeping them apart from the secret means a copied instruction page is not also a copied credential.
Help the client store and use it safely
Delivery is not finished when the client can read the value. It is finished when the server can read it securely and uses it to verify incoming signatures.
- Store it in a secrets manager or protected environment variable that the server process can read, with access limited to the application and the people who operate it.
- Keep it out of source code, logs and webhook payloads. The secret is used to compute or verify a signature. It never travels in the request body, and it should not appear in debug output, repositories or support tickets. Check what your deployment tooling captures before turning on verbose diagnostics.
- Verify signatures on the server. The receiver recomputes the signature over the raw request body with the shared secret and compares it with the header the sender set. Signing proves the request is genuine and unaltered; it does not encrypt the payload. HackerOne's guide to signing webhooks covers why the raw body and the correct secret both matter.
- Run a test event. Have the client confirm that a valid signature is accepted and a deliberately broken one is rejected. That catches the usual mistakes: the wrong endpoint's secret, or a body parsed before verification. Keep test and production credentials separate where the integration supports it.
Reduce the risk after delivery
The handoff should leave a usable record, not a trail of extra copies.
- Record who was authorised and when. Log the recipient, the endpoint or client, and the time of the handoff. Never the value. If you cannot tell whether a link was opened or who could reach a shared folder, treat that as a reason to tighten the process next time.
- Rotate on any suspected exposure. A secret pasted into a ticket, sent to the wrong address or found in a log is no longer private. Generate a replacement, update the endpoint, and invalidate the old value. Removing a sharing link does not undo an exposure; only rotation does.
- Agree the rotation process now. Decide who requests, creates and installs a replacement, whether the implementation supports a short overlap, and how you will test the new value before retiring the old one. A known procedure beats an urgent exchange during an outage.
- Clean up. Once the client confirms retrieval, revoke temporary access and delete stray copies in drafts, tickets and notes. Check the retention rules of each system involved; deleting a message from one view rarely removes it from backups.
Troubleshoot without exposing the secret
A delivery problem is not a reason to resend the credential through a weaker channel. First work out which of three things is wrong: the client cannot retrieve the secret, cannot configure the endpoint, or receives requests but cannot validate the signatures.
- Retrieval failed or the window expired. Confirm the recipient again and issue a new controlled handoff. Do not paste the value into a ticket, and do not ask the client to send theirs back for comparison.
- Signature mismatch. Almost always a verification-input problem: the wrong secret for that endpoint, a body that was reformatted before hashing, or a header read incorrectly. Have the client test with a known event through the sender's testing tools.
- Requests never arrive. That is a delivery or routing issue, not a credential issue. Check timestamps, response codes and endpoint selection before anyone considers rotating. Stripe's webhook documentation is a useful model for separating endpoint registration and event delivery from signature verification.
- Share redacted diagnostics. Event id, timestamp, endpoint and error category are enough. Strip the secret, the full signature where it is sensitive, and private payload fields, and check the redaction before you send a sample request.
Verify the recipient, hand the secret over once through a channel that forgets it, make sure it lands in a secrets store, and rotate without hesitation if it may have leaked. For the wider pattern of one-time links in engineering workflows, see secure link sharing for developers.