Sign in to fill these examples with your own keys. Sign in Start free trial

Managing webhooks

Get delivery events POSTed to your server as a SendGrid Event Webhook array.

Add a delivery webhook and PostShiba POSTs an event to your URL each time a message is processed, delivered, deferred, bounced, dropped, reported as spam, or unsubscribed. The body uses the SendGrid Event Webhook format, so an existing SendGrid event handler can read it.

Before you start

  • A URL on the public internet that accepts POST. Production URLs must use https. Private and internal addresses are refused.
  • For the API route, a Full access key from Create an API key.

Add an endpoint in the dashboard

  1. Open Webhooks in the dashboard and click Add endpoint.
  2. Enter the URL.
  3. Pick a Scope. Team receives every event. Cluster or Tenant receives only events from that cluster or tenant.
  4. Pick the Event types. New endpoints start with all seven emitted events. See Event types.
  5. Save, then copy the Signing secret from the endpoint page. You need it to verify requests.

The endpoint page also shows whether the URL is reachable and lists the 50 most recent deliveries with their status and last error.

Add an endpoint with the API

create-webhook.sh
1curl -sS -X POST \ 2 -H 'Authorization: Bearer YOUR_API_KEY' \ 3 -H 'Content-Type: application/json' \ 4 -d '{"webhook_endpoint": {"url": "https://hooks.example.com/postshiba", "event_types": ["delivered", "bounce"]}}' \ 5 https://app.postshiba.com/api/v1/teams/KjkAJW/webhook_endpoints

The create response is the only API response besides show that includes secret. Store it with your other secrets. To limit the endpoint to one cluster or one tenant, add cluster_id or tenant_id. Set one or neither. Every endpoint action is on Webhooks.

What each request looks like

Each POST carries one event in a JSON array:

Header Value
Content-Type application/json
X-Capsule-Timestamp Unix time, as a string, when the request was signed.
X-Capsule-Signature sha256= followed by the hex HMAC-SHA256 of {timestamp}.{body}.

Return any 2xx status to acknowledge the event. Anything else, including a redirect, a timeout, or a refused connection, counts as a failure and is retried. PostShiba waits up to 5 seconds to connect and 10 seconds for your response. See Retries and replays.

Endpoint status

PostShiba sends nothing to your URL except events. There are no health checks, so your server only wakes up when there is something to handle.

Status comes from real deliveries:

Status Meaning
No deliveries yet Nothing has been sent.
Up The last delivery returned 2xx.
Retrying Recent deliveries failed. New events are still sent.
Down 8 deliveries failed in a row. New events wait in a queue. See Retries and replays.

Send a test event

Click Send test event on the endpoint, or call POST /api/v1/webhook_endpoints/:id/send_test. PostShiba posts one signed sample event and shows what your server answered. The sample has "test": true and the X-Capsule-Test: 1 header, so you can tell it from real traffic. A 2xx marks the endpoint Up and sends anything queued while it was down.

Next steps