Webhooks
Endpoints, every delivery attempt, and how to replay one.
The Webhooks view has three tabs: the events your account produced, the deliveries made from them, and the endpoints they were sent to. Events have their own page; this one is about the other two.
Webhook deliveries
| Method | Endpoint | Status | Duration | Attempt |
|---|---|---|---|---|
| POST | /webhooks/wajub | 500 | 10021 ms | 1 of 5 |
| POST | /webhooks/wajub | 500 | 240 ms | 2 of 5 |
| POST | /webhooks/wajub | 200 | 142 ms | 3 of 5 |
Deliveries
One row per attempt, not per event. A delivery retried three times is three rows sharing one delivery id.
| Column | Note |
|---|---|
| Status | success, retrying or failed |
| Response code | What your endpoint answered, empty on a network error |
| Duration | How long your endpoint took. A row at 10,000 ms is a timeout |
| Attempt | 1 to 5 |
| Endpoint | Which URL, when you have several |
Filters: search over the event, status, endpoint, and a date range in whole days. Fifty per page.
The detail panel carries the payload that was sent and the body your endpoint returned, which is
how you find out that your 500 came with a stack trace you can read from here.
Replaying
Two ways, both counted against your plan's monthly max_webhooks allowance.
| Action | Scope |
|---|---|
| Retry | One delivery |
| Bulk retry | Up to 100 failed deliveries at once, within a window, optionally for one endpoint |
Bulk retry only picks up deliveries whose status is failed, inside the window you choose, which
defaults to the last 24 hours. Each delivery in the batch consumes one unit of the allowance, and
the batch stops when the allowance runs out.
Fix the endpoint before you replay
A replay repeats the same payload against the same URL. If the handler still throws, you have spent your allowance reproducing the failure. Deploy the fix, replay one delivery, check it went green, then bulk replay the rest.
Endpoints
Creating one takes a URL and a list of event types.
| Field | Rule |
|---|---|
| URL | A valid URL, up to 2,048 characters, and not a private or internal address |
| Events | At least one, each from the list Konsole offers |
| Description | Free text, worth using when you have several |
Konsole checks the event names, the API does not
The picker only offers valid types and refuses anything else. POST /webhooks accepts any
non-empty array, so a typo made through the API is stored and silently never matches. See the
event catalogue.
Private and internal addresses are refused on purpose: an endpoint pointing at localhost or at a
private range would turn Wajub's delivery worker into a probe of the internal network. For local
development, use wajub listen.
The secret
Each endpoint has its own signing secret, shown once at creation. Afterwards, Reveal secret shows it again, behind a re-confirmation of your password, and the action is recorded.
Rotating is done from the API with POST /webhooks/{id}/rotate-secret. Deploy the new secret
before rotating, or the deliveries between the rotation and your deploy will fail signature
verification.
Promoting a sandbox endpoint to live
A sandbox endpoint can be copied to live in one action. It carries over the URL and the event list, and it gets a new secret, because a sandbox secret has been on developer laptops.
Update your live environment variable after promoting
The live endpoint's secret is not the sandbox one. A server still holding the old value will reject every live delivery with a signature error.
The connectivity test is not a real event
Send test posts a fixed payload to the endpoint, signed with its real secret. It proves the URL is reachable and that your signature check passes. It does not prove your handler works, because the payload is shaped differently from a real delivery.
Four differences from a real delivery, and each one has bitten someone.
| Real delivery | Send test |
|---|---|
The type is in event | The type is in type |
Carries api_version, pending_webhooks, request | Carries none of them |
Sends X-Wajub-Delivery-Id | Does not |
Recorded with status success | Recorded with status delivered |
Do not write your handler against the test payload
A handler that reads payload.type works with Send test and never fires in production, where
the field is event. Test the signature with this button, and test the handler with
wajub trigger, which produces real events.