PlumHelp
Help · Workspace settings

Webhooks

Have Plum tell another system when an account, contact, deal, license or holding changes, by sending it a signed message within a few minutes.

Owners and admins

Add an endpoint

  1. Open API and webhooks in the workspace settings.
  2. Under Add an endpoint, enter the https address that should receive the messages, and a description if you like.
  3. Tick the events it should hear about, and select Add endpoint.
  4. Open the endpoint and copy its signing secret into the receiving system, so it can check each message came from Plum.

The address must be https and on the public internet. Plum refuses addresses on private networks, and checks every address a name points to each time it sends.

Events

account.created, account.updated
An account is added or changes.
contact.created, contact.updated
A contact is added or changes.
deal.created
A deal is added.
deal.stage_changed
A deal moves stage. The data includes from_stage.
deal.won, deal.lost
A deal moves into a won or a lost stage. Sent as well as deal.stage_changed.
license.created, license.updated
A license is recorded or changes.
holding.created
Something sold once, a project or a retainer is recorded.
holding.delivered
Something sold is marked delivered.

What is sent

A POST with a JSON body: { "event": "deal.won", "occurred_at": "2026-10-16T14:02:11Z", "data": { the record as it is now } }.

With three headers: Plum-Event, the event's name; Plum-Delivery, the delivery's number, the same on every retry, so you can ignore one you've already handled; and Plum-Signature, which proves it came from Plum.

Check the signature

  1. Read the raw body exactly as it arrived, before parsing it.
  2. Split the Plum-Signature header on commas. It looks like t=1760623331,v1= followed by 64 characters. t is the time it was signed, in seconds since 1970; v1 is the signature.
  3. Refuse it if t is more than five minutes from your clock.
  4. Join t, a full stop and the raw body, and compute an HMAC-SHA256 of that, using the whole signing secret, whsec_ included, as the key. Write it as lowercase hex.
  5. Compare it with v1 using a constant-time comparison. If they match, the message is from Plum and unchanged.

Answering, and retries

Answer with any 2xx status within 10 seconds. Anything else, a redirect, or no answer counts as a failure: Plum tries again after 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours, 12 hours and 24 hours, and gives up after the eighth try. Messages to one endpoint are sent in order, and while one is failing the ones after it wait.

After 50 failures in a row, Plum switches the endpoint off. Turn it back on when the receiver is fixed; messages still waiting are then sent. The last 20 deliveries and how each went are listed on the settings page.

Pause, replace the secret, delete

  • Pause stops sending. Changes made while it is paused aren't queued for it.
  • Replace the secret makes a new one at once; the old one stops verifying. Update your receiver straight away.
  • Delete removes the endpoint and anything still waiting to be sent to it.

Every record's whole content is sent, so send it only to systems you trust with your customer data.

Related