What are webhooks and when should I use them?
Webhooks let your systems receive instant updates when something changes in SpeakUp. Instead of polling the API for changes, your system receives an HTTP POST request the moment an Issue is created or updated.
Use webhooks when your system needs to react to changes quickly, for example to open a ticket in your case management platform as soon as a report arrives, or to keep a data warehouse current without scheduled jobs.
On this page: Webhooks or the API · What triggers a webhook · Before you start · How delivery works · Limitations
Webhooks or the API
Both give you the same Issue data. They differ in who initiates the exchange.
| Webhooks | Public API | |
|---|---|---|
| Who initiates | SpeakUp calls your system. | Your system calls SpeakUp. |
| Timing | The moment a change is saved. | Whenever you ask. |
| What you receive | Identifiers and what changed. | The full Issue. |
| Requires | An endpoint SpeakUp can reach. | Credentials for your system to call with. |
Most integrations use both. The webhook tells you an Issue changed and which fields changed, then your system calls Retrieving Issues to fetch the new values. Webhook payloads are deliberately small and carry identifiers rather than Issue content.
What triggers a webhook
Webhooks fire on two Issue events.
| Trigger | Fires when |
|---|---|
| Issue Created | A new Issue is submitted to SpeakUp. |
| Issue Updated | An existing Issue is modified. |
Issue Updated covers a wide range of changes: core fields such as status, assignee, and labels, plus comments, documents, folders, tasks, linked Issues, forms, messages and their translations, and User role assignments.
Drafts do not trigger webhooks. A description, comment, or message only fires an event once it is saved or sent. Discarded drafts fire nothing.
For the complete list and what each one reports, see Webhook events and payloads.
Before you start
- The Webhooks package must be enabled on your SpeakUp system. Contact your Customer Success Manager if you are not sure by clicking 'Support' and 'Contact support'.
- You must have the Administrator role. Only administrators can create, update, or delete webhook configurations.
- You need a target endpoint in the receiving system, and its URL.
Once those are in place, see how do I configure webhooks?
How delivery works
SpeakUp sends an HTTP POST request to your endpoint with Content-Type: application/json. Any response below 400 is treated as a successful delivery.
Two properties of delivery shape how you should build the receiving end.
Failed deliveries are not retried
If a request fails or times out, it is logged and not attempted again. There is no queue and no backoff. A missed event is missed.
If your endpoint is unavailable when an event fires, that event does not arrive later.
Your endpoint has 10 seconds
The webhook times out after 10 seconds. A timeout counts as a failed delivery, and failed deliveries are not retried.
Webhook failures do not block Issue operations in SpeakUp. Case handlers are unaffected by an endpoint that is down.
Limitations
| Limitation | What it means for your integration |
|---|---|
| Issue-centric events only | Only Issue Created and Issue Updated exist. There are no events for other objects. |
| No Auth or Basic Auth only | Bearer tokens, signed payloads, and mutual TLS are not supported. |
| No retry on failure | Failed deliveries are logged, not reattempted. Plan for gaps, for example a periodic reconciliation against the API. |
| 10 second timeout | A slow response is a failed delivery. |
| Administrator only | Webhook configuration cannot be delegated to other roles. |
Next steps
- How do I configure webhooks?
- Webhook events and payloads
- Retrieving Issues to fetch the Issue after a webhook arrives