Skip to content

Receive events with webhooks

Have Trabbly send your server a signed message when a post is published, publishing fails, or a reviewer decides.

Available on EnterpriseUpdated 2 min read
On this page
  1. Events
  2. Add a webhook
  3. What Trabbly sends
  4. Check the signature
  5. Answering and retries
  6. Test, switch off or delete

Webhooks tell your own systems when something happens in Trabbly, so they don't need to keep asking the API. They are part of the Enterprise plan. Owners and admins add and manage them.

Events

Event Sent when
post.published A post was published on a platform.
post.failed Publishing a post failed.
approval.decided A reviewer approved a post or asked for changes.

Add a webhook

  1. Open Settings, then API access.
  2. Under Webhooks, select Add webhook.
  3. Enter Your server's address. It must be a public HTTPS address.
  4. Under Events to send, tick the events you want.
  5. Choose the brands, or All brands.
  6. Select Add webhook.

The signing secret is shown only once. Keep it with your server's settings: you use it to check that each event really comes from Trabbly.

An organisation can have up to 10 webhooks.

What Trabbly sends

A JSON POST with:

  • id: the event's own id, for example evt_01jb8z6y0q4m7v2k3n5p9r1s2t.
  • type: the event, for example post.published.
  • created_at: when it happened, in UTC.
  • organisation_id: your organisation.
  • data: the post id, the platform version (variant_id), the brand id, the platform (network), the status and, for a published post, its permalink.

post.failed includes the reason, and approval.decided includes the stage, the decision and any note.

Check the signature

Each event carries Trabbly-Signature: t=TIMESTAMP,v1=SIGNATURE. The signature is an HMAC-SHA256 of the timestamp, a full stop and the raw body, made with your signing secret. Before trusting an event:

  1. Work out the same HMAC with your secret.
  2. Compare it with v1 using a constant-time comparison.
  3. Reject events whose timestamp is more than a few minutes old.

The developer guide in the app has a ready-made example.

Answering and retries

  • Answer with any 2xx status.
  • Other answers are retried up to five more times over about nine hours (after 1 minute, 5 minutes, 30 minutes, 2 hours and 6 hours).
  • After 20 failures in a row the webhook is switched off until you switch it back on.
  • Trabbly-Delivery stays the same on retries, so you can ignore repeats.
  • Redirects aren't followed.

Test, switch off or delete

Each webhook has Send test event, Switch off (or Switch on) and Delete. Webhooks are only delivered while your organisation's plan includes the API.

Was this article helpful?

Ask a question