Webhook Setup

Purpose

This is how Dokploy tells your phone that something happened. Set it up once per server, and deploys, backups, and alerts become push notifications. Admin-only: the row stays hidden for everyone else.

---

Roles

• Dokploy admin/owner - can enable, re-sync, rotate, and disable the relay.
• Other roles - no access; ask an admin to set it up.

---

User Flow

Know when to come here

Step 1: Recognize the moments

• Right after first sign-in, if you want notifications at all.
• When the row says "Re-sync pending" or you changed your Dokploy address.
• After rotating the secret.

Result:

• You act only when needed - re-tapping a healthy relay is safe and creates no duplicates.

---

Enable the relay

Step 2: One tap

1. Open Settings, then Notifications, then Push setup. The row shows connected or not connected at a glance.
2. Tap Enable webhook.

Result:

• The screen shows the relay Enabled with the endpoint and a hidden secret, plus the last sync time. Nothing needs copying by hand.

Note (older Dokploy):

• On very old Dokploy versions automatic setup can fail. You'll see a message with copy buttons for the endpoint and secret - paste those into Dokploy, then Notifications, then Custom. Same result, a few extra steps.

---

Read the screen

Step 3: Know the fields

• Endpoint - where Dokploy sends events. Copy button included.
• Secret - the code Dokploy sends along with events so Dokman knows they're genuine. Tap to reveal, copy if needed. Never share it publicly.
• Status - Enabled, Disabled, or Re-sync pending.
• Headers stored - a warning here means tap Re-sync.

Result:

• You can confirm health at a glance and hand the values to manual setups.

---

Re-sync, rotate, disable

Step 4: Maintain

1. Re-sync webhook when it says "Re-sync pending" (Dokploy was offline), after moving Dokploy, reinstalling it, or rotating the secret. Safe to re-tap anytime.
2. Rotate Secret makes a brand-new secret and - when the relay is enabled - updates Dokploy for you. If Dokploy was offline you'll see "re-sync pending": tap Re-sync once it's back.
3. Turn off removes the webhook from Dokploy. Pushes stop. Re-enable anytime.

Result:

• The relay stays healthy across moves, reinstalls, and rotations.

---

Screens Involved

• Push setup screen (status chip, endpoint/secret fields with copy, Re-sync webhook, Rotate Secret, Turn off)
• Settings Notifications row (connected / not connected indicator)

---

Inputs

User Inputs:

• Enable / Re-sync / Rotate / Disable confirms
• Manual endpoint + secret paste (older Dokploy only)

---

Outputs

• dokman-relay webhook created, synced, rotated, or removed in Dokploy
• Push delivery started or stopped accordingly

---

Error Handling and Edge Cases

Scenario	System Behavior
Row hidden entirely	Not a Dokploy admin - ask an owner
"Admin access required"	Same - admin-only screen
"Retry later" / unreachable	Dokploy can't be reached - check address, VPN, server state
Rotated while Dokploy offline	"Re-sync pending" - tap Re-sync once it's back