postalserver / postalserver/docs

Webhook documentation isn't clear on status vs event

Open
#81 1 comment 0 reactions 0 assignees View on GitHub
Dominant language
TypeScript
Stars
143
Forks
65
PR merge metrics
No merged PRs in 30d

Description

The documentation at https://docs.postalserver.io/developer/webhooks specifies "the following statuses may be delivered":

- **MessageSent** - when a message is successfully delivered to a recipient/endpoint.
- **MessageDelayed** - when a message's delivery has been delayed. This will be sent each time Postal attempts a delivery and a message is delayed further.
- **MessageDeliveryFailed** - when a message cannot be delivered.
- **MessageHeld** - when a message is held.

But when actually testing this, it seems that the actual values sent for the `status` field are:

- **Sent**
- **SoftFail**
- **HardFail**
- **Held**

Instead, the values at the top are used in the top-level `event` field, which is not shown at all in the examples on the page. Think it would be useful and much more clear if a full webhook HTTP POST was shown somewhere on the page:

```
{
"event":"MessageSent",
"timestamp":1740935264.79515,
"payload": {
"message":{
id":10,
"token":"...",
"direction":"outgoing",
"message_id":"...",
"to":"...",
"from":"...",
"subject":"...",
"timestamp":1740935259.8611999,
"spam_status":"NotChecked",
"tag":""
},
"status":"Sent",
"details":"...",
"output":"250 2.0.0 OK ...",
"sent_with_ssl":true,
"timestamp":1740935264.785198,
"time":0.5
},
"uuid":"62498fda-ffc5-42f9-b23e-cea5274c513a"
}
```

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.