Skip to content

Webhooks

Webhooks let you receive message status updates and inbound user events.

We send a webhook whenever a message change state, either by our systems or our providers, and when you receive incoming messages on virtual numbers or RCS agents.

Your inbound webhook IP restrictions

Our webhook callbacks originate from different IPs, which are subject to change on short notice. We acknowledge that you may want to secure your infrastructure with IP restrictions, but we do not advise you to rely on IP-based restrictions.

In case you require the originating webhook IP address, this can be looked up via our DNS service. Use the dig command to, or similar, Lookup IPs via CLI - for IPv4 use A and IPv6 use AAAA.

1
2
3
4
5
# Get IPv4 addresses for EU-Setup
dig +short A ips.gatewayapi.eu

# Get IPv6 addresses for the Global cluster
dig +short AAAA ips.gatewayapi.com

If using IP based firewalling we recommend setting up a cron job or a script to refresh your firewall rules automatically to prevent service disruption when our IP pool updates.

To ensure reliable delivery of webhook events the system follows a set of rules to determine if the delivery of an event was sucessful.

  • The receiving server must reply within 5 seconds.
  • The response must be with a HTTP status code in the 2xx range.
  • If using HTTPS the receiving server must provide a valid TLS certificate.

In case the delivery fails, the webhook event is then scheduled for delivery at a later point in time. The exact algorithm used is subject to change, but it includes exponential backoff and randomization in time to smooth out large spikes in events that might overwhelm the receiving server.

If the delivery attempts keep failing a high number of times and for at least 24 hours, the event is eventually dropped and no further retries will be made.

Webhooks can be configured and tested in the GatewayAPI Dashboard or its EU variant.

Receiving SMS Messages

Webhooks are also used to receive SMS messages, which is often referred to as MO SMS.

Prerequisites

In order to receive an SMS, you will need a short code and/or keyword to which the user sends the SMS. This short code and/or keyword is leased to you, so when we receive an SMS on the specific short code, with the specific keyword, we know where to deliver the SMS.

You can either lease a keyword on a shared short code, such as +45 1204, or you can lease an entire short code, such as +45 60575797. Contact us via the live chat if you need a new short code and/or keyword.

If you lease the keyword “foo” on the short code 45 1204, a Danish (+45) user would send i.e. “foo hello world” to “1204”, and you will receive the SMS.

Once you have a keyword lease, you will need to assign the keyword to a webhook. You can do this from the dashboard.

  • If you do not have a webhook, add one
  • Click the webhook you want to receive SMS messages
  • Click the tab “Keywords”
  • Make sure the checkbox next to “Assign” is checked for the keywords you want to assign to this webhook

If you have any questions, please contact us using the live chat.